email-smtp-send

Email SMTP 发送

核心目标

• 使用环境变量配置的凭据，通过 SMTP 发送邮件。
• 按需将本地文件作为 MIME 邮件内容的附件。
• 可选择将已发送邮件追加到 IMAP 已发送邮箱，以便在不同客户端间查看。
• 在发送前验证 SMTP 和已发送邮件同步配置。
• 返回机器可读的 JSON 状态或错误输出。

工作流

1. 配置 SMTP 环境变量（参见 references/env.md 和 assets/config.example.env）。
2. 可选：配置 IMAP 已发送邮件同步环境变量；启用同步时安装 imapclient。
3. 验证配置：

python3 scripts/smtp_send.py check-config

4. 发送一封邮件：

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

5. 发送邮件并添加附件：

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

6. 发送邮件并同步到已发送邮箱：

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"

输出约定

• check-config 会输出经过脱敏的 SMTP 配置、默认值和已发送邮件同步配置 JSON。
• send 成功时会输出一个 type=status JSON 对象，其中包含：
  • event=smtp_sent
  • 发件人、收件人摘要、主题、SMTP 主机/端口
  • message_id
  • attachment_count 和附件元数据 attachments[]
  • 包含 enabled、required、appended 以及同步元数据/错误的 sent_sync 对象
• send 失败时会将 type=error JSON 输出到 stderr，事件类型为以下之一：
  • event=smtp_send_invalid_args
  • event=smtp_send_failed
  • event=smtp_sent_sync_failed（仅在同步为必需且同步失败时）

参数

• send --to：必需的收件人，可重复指定或以逗号分隔。
• send --cc：可选的抄送收件人。
• send --bcc：可选的密送收件人。
• send --subject：可选主题（默认使用环境变量中的值）。
• send --body：可选正文（默认使用环境变量中的值）。
• send --content-type：plain 或 html。
• send --from：可选的发件人覆盖值。
• send --attach：可选的本地附件路径，可重复指定或以逗号分隔。
• send --max-attachment-bytes：每个附件允许的最大字节数。
• send --message-id：可选的 Message-ID 标头。
• send --in-reply-to：可选的 In-Reply-To 标头。
• send --references：可选的 References 标头。
• send --sync-sent|--no-sync-sent：强制为本次发送启用/禁用 IMAP 已发送邮件同步。
• send --sent-mailbox：覆盖已发送邮箱。
• send --sent-flags：以逗号分隔的 IMAP APPEND 标志（默认 \Seen）。
• send --sent-sync-required：如果 SMTP 发送成功但已发送邮件同步失败，则返回非零状态码。

环境变量默认值：

• 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
• 兼容性回退变量：IMAP_HOST、IMAP_PORT、IMAP_SSL、IMAP_USERNAME、IMAP_PASSWORD、IMAP_CONNECT_TIMEOUT

依赖项

• 已发送邮件同步模式需要 imapclient：

python3 -m pip install imapclient

错误处理

• 环境变量配置无效时，以代码 2 退出。
• 发送失败时，以代码 1 退出。
• 如果同步为必需（--sent-sync-required 或 SMTP_SYNC_SENT_REQUIRED=true），同步失败时以代码 1 退出。

参考资料

• references/env.md

资源文件

• assets/config.example.env

脚本

• scripts/smtp_send.py