email-smtp-send

SKILL.md

Email SMTP Send

Core Goal

Send outbound email via SMTP with env-configured credentials.

Attach local files into MIME email payload when requested.

Optionally append the sent message to IMAP sent mailbox for cross-client visibility.

Validate SMTP and sent-sync configuration before delivery.

Return machine-readable JSON status/error output.

Workflow

Configure SMTP env vars (see references/env.md and assets/config.example.env).

Optional: configure IMAP sent-sync env vars and install imapclient when sync is enabled.

Validate configuration:

python3 scripts/smtp_send.py check-config

Send one email:

python3 scripts/smtp_send.py send \
  --to recipient@example.com \
  --subject "SMTP test" \
  --body "Hello from email-smtp-send"

Send with attachments:

python3 scripts/smtp_send.py send \
  --to recipient@example.com \
  --subject "Package delivery" \
  --body "See attachments." \
  --attach ./report.pdf \
  --attach ./appendix.xlsx

Send and sync to sent mailbox:

python3 scripts/smtp_send.py send \
  --to recipient@example.com \
  --subject "Synced send" \
  --body "This message will be appended to Sent Items." \
  --sync-sent \
  --sent-mailbox "Sent Items"

Output Contract

check-config prints sanitized SMTP config + defaults + sent-sync config JSON.

send success prints one type=status JSON object containing:

event=smtp_sent

sender, recipient summary, subject, SMTP host/port

message_id

attachment_count and attachments[] metadata

sent_sync object with enabled, required, appended, and sync metadata/error

send failures print type=error JSON to stderr with one of:

event=smtp_send_invalid_args

event=smtp_send_failed

event=smtp_sent_sync_failed (only when sync is required and sync fails)

Parameters

send --to: required recipient, repeatable or comma-separated.

send --cc: optional CC recipients.

send --bcc: optional BCC recipients.

send --subject: optional subject (defaults from env).

send --body: optional body (defaults from env).

send --content-type: plain or html.

send --from: optional sender override.

send --attach: optional local attachment path, repeatable or comma-separated.

send --max-attachment-bytes: max bytes allowed per attachment.

send --message-id: optional Message-ID header.

send --in-reply-to: optional In-Reply-To header.

send --references: optional References header.

send --sync-sent|--no-sync-sent: force-enable/disable IMAP sent sync for this send.

send --sent-mailbox: override sent mailbox.

send --sent-flags: IMAP APPEND flags, comma-separated (default \Seen).

send --sent-sync-required: return non-zero if SMTP succeeds but sent sync fails.

Environment defaults:

SMTP_HOST, SMTP_PORT, SMTP_SSL, SMTP_STARTTLS

SMTP_USERNAME, SMTP_PASSWORD, SMTP_FROM, SMTP_CONNECT_TIMEOUT

SMTP_SUBJECT, SMTP_BODY, SMTP_CONTENT_TYPE

SMTP_MAX_ATTACHMENT_BYTES

SMTP_SYNC_SENT, SMTP_SYNC_SENT_REQUIRED

SMTP_SENT_IMAP_HOST, SMTP_SENT_IMAP_PORT, SMTP_SENT_IMAP_SSL

SMTP_SENT_IMAP_USERNAME, SMTP_SENT_IMAP_PASSWORD

SMTP_SENT_IMAP_MAILBOX, SMTP_SENT_IMAP_FLAGS, SMTP_SENT_IMAP_CONNECT_TIMEOUT

compatibility fallbacks: IMAP_HOST, IMAP_PORT, IMAP_SSL, IMAP_USERNAME, IMAP_PASSWORD, IMAP_CONNECT_TIMEOUT

Dependency

Sent-sync mode requires imapclient:

python3 -m pip install imapclient

Error Handling

Invalid env config exits with code 2.

Send failure exits with code 1.

If sync is required (--sent-sync-required or SMTP_SYNC_SENT_REQUIRED=true), sync failure exits with code 1.

References

references/env.md

Assets

assets/config.example.env

Scripts

scripts/smtp_send.py