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