email-smtp-send

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Email SMTP Send

SMTP邮件发送

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.

通过配置环境变量的凭据，借助SMTP发送外发邮件。
按需将本地文件附加到MIME邮件负载中。
可选择将已发送邮件追加到IMAP已发送邮件箱，实现跨客户端可见。
投递前验证SMTP和已发送同步配置。
返回机器可读的JSON格式状态/错误输出。

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:

bash

python3 scripts/smtp_send.py check-config

Send one email:

bash

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

Send with attachments:

bash

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:

bash

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"

配置SMTP环境变量（参考

references/env.md

和

assets/config.example.env

）。

可选：配置IMAP已发送同步环境变量，若启用同步功能需安装
```
imapclient
```
。
验证配置：

bash

python3 scripts/smtp_send.py check-config

发送单封邮件：

bash

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

发送带附件的邮件：

bash

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

发送邮件并同步至已发送邮件箱：

bash

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)

```
check-config
```
命令会打印经过脱敏的SMTP配置、默认值以及已发送同步配置的JSON格式内容。
```
send
```
命令执行成功时，会输出一个
```
type=status
```
的JSON对象，包含：
- ```
event=smtp_sent
```
- 发件人、收件人摘要、邮件主题、SMTP主机/端口
- ```
message_id
```
- ```
attachment_count
```
  和
```
attachments[]
```
  元数据
- ```
sent_sync
```
  对象，包含
```
enabled
```
  、
```
required
```
  、
```
appended
```
  以及同步元数据/错误信息
```
send
```
命令执行失败时，会将
```
type=error
```
的JSON输出到标准错误流，对应以下事件之一：
- ```
event=smtp_send_invalid_args
```
- ```
event=smtp_send_failed
```
- ```
event=smtp_sent_sync_failed
```
  （仅当同步为必填项且同步失败时触发）

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

```
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

Dependency

依赖项

Sent-sync mode requires
```
imapclient
```
:

bash

python3 -m pip install imapclient

已发送同步模式需要
```
imapclient
```
：

bash

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
```
.

环境变量配置无效时，退出码为
```
2
```
。
邮件发送失败时，退出码为
```
1
```
。
若同步为必填项（
```
--sent-sync-required
```
或
```
SMTP_SYNC_SENT_REQUIRED=true
```
），同步失败时退出码为
```
1
```
。

References

参考文档

```
references/env.md
```

```
references/env.md
```

Assets

资源文件

```
assets/config.example.env
```

```
assets/config.example.env
```

Scripts

脚本文件

```
scripts/smtp_send.py
```

```
scripts/smtp_send.py
```