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

1. Configure SMTP env vars (see references/env.md and assets/config.example.env).
2. Optional: configure IMAP sent-sync env vars and install imapclient when sync is enabled.
3. Validate configuration:

python3 scripts/smtp_send.py check-config

1. Send one email:

python3 scripts/smtp_send.py send \
  --to [email protected] \
  --subject "SMTP test" \
  --body "Hello from email-smtp-send"

1. Send with attachments:

python3 scripts/smtp_send.py send \
  --to [email protected] \
  --subject "Package delivery" \
  --body "See attachments." \
  --attach ./report.pdf \
  --attach ./appendix.xlsx

1. Send and sync to sent mailbox:

python3 scripts/smtp_send.py send \
  --to [email protected] \
  --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=smtpsent - sender, recipient summary, subject, SMTP host/port - messageid - attachmentcount and attachments[] metadata - sentsync object with enabled, required, appended, and sync metadata/error

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

- event=smtpsendinvalidargs - event=smtpsendfailed - event=smtpsentsyncfailed (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:

• SMTPHOST, SMTPPORT, SMTPSSL, SMTPSTARTTLS
• SMTPUSERNAME, SMTPPASSWORD, SMTPFROM, SMTPCONNECT_TIMEOUT
• SMTPSUBJECT, SMTPBODY, SMTPCONTENTTYPE
• SMTPMAXATTACHMENT_BYTES
• SMTPSYNCSENT, SMTPSYNCSENT_REQUIRED
• SMTPSENTIMAPHOST, SMTPSENTIMAPPORT, SMTPSENTIMAP_SSL
• SMTPSENTIMAPUSERNAME, SMTPSENTIMAPPASSWORD
• SMTPSENTIMAPMAILBOX, SMTPSENTIMAPFLAGS, SMTPSENTIMAPCONNECTTIMEOUT
• compatibility fallbacks: IMAPHOST, IMAPPORT, IMAPSSL, IMAPUSERNAME, IMAPPASSWORD, IMAPCONNECT_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 SMTPSYNCSENT_REQUIRED=true), sync failure exits with code 1.

References

• references/env.md

Assets

• assets/config.example.env

Scripts

• scripts/smtp_send.py