通过 SMTP 发送邮件

如果你的应用已经支持 SMTP，只需修改主机、端口和凭据即可将其指向我们的中继服务。框架、内容管理系统、打印机以及其他能向 SMTP 中继提交邮件的软件都可以使用此方式。

通过 SMTP 提交的邮件与通过邮件 API发送的邮件处理方式完全相同：域名验证、IP 池、DKIM 签名、屏蔽处理、追踪、事件和分析均一致。SMTP 只是同一产品的另一个入口，你为其中一种方式配置的内容同样适用于另一种。

当你希望保留应用现有的邮件构建代码时，选择 SMTP 中继服务。当你需要结构化的请求字段或已存储模板时，选择邮件 API。SMTP 从 MIME 消息中获取内容，从 API 密钥的配置中获取发送选项。

前提条件

• 一个已验证的发送域名。 你在 MAIL FROM 中填写的地址（以及消息的 From 请求头）必须属于你在此工作区中已验证的域名。参见发送域名。
• 一个具有 emails 权限范围的 API 密钥。 SMTP 使用你常规的 API 密钥，无需单独的 SMTP 凭据。在 Developers > API keys 中创建一个已启用邮件发送的密钥。没有 emails 权限范围的密钥无法发送邮件，仅限 verify 的密钥同样不行。

连接设置

将客户端指向你密钥所在区域的 SMTP 主机。区域即密钥本身的前缀：bk_eu1_... 密钥通过 eu1 主机发送，bk_us1_... 密钥通过 us1 发送。使用其他区域的密钥进行身份验证会失败，并返回 535 响应，指明应使用的主机。

选择你的客户端支持的方式：

• 端口 465，隐式 TLS (SMTPS)。 连接从第一个字节起即加密，在发送任何命令之前。在大多数库中对应的是 "SSL/TLS" 或 "SMTPS" 选项。
• 端口 587 和 2525，STARTTLS。 连接以明文方式打开，然后在身份验证之前通过 STARTTLS 命令升级为 TLS。对应的是 "STARTTLS" 选项，有时简单标记为 "TLS"。如果你的网络屏蔽了 587，请使用 2525。

TLS 版本： 端口 465、587 和 2525 支持 TLS 1.2 和 TLS 1.3。请将客户端配置为使用 TLS 1.2 或更高版本。不支持 TLS 1.0 和 TLS 1.1。

无论哪种方式，会话在发送凭据之前都已加密，因此凭据不会以明文传输：在 587 和 2525 端口上，STARTTLS 完成之前会拒绝 AUTH。不提供端口 25 用于邮件提交。

身份验证

使用 AUTH PLAIN 或 AUTH LOGIN 进行身份验证。用户名是固定字符串 bird，密码是你的 API 密钥：

Username: bird
Password: bk_eu1_your_api_key

用户名是一个固定字面值，本身没有任何身份含义。密码字段中的 API 密钥才是实际的身份验证凭据。在大多数 SMTP 工具中，你将 API 密钥粘贴到密码字段，并将用户名设置为 bird。撤销密钥会在数秒内切断其 SMTP 发送能力，包括正在进行的连接。

哪些来自消息，哪些来自密钥配置

MIME 消息中有对应位置的内容都来自消息本身：From、To、Cc 和 Reply-To 请求头、主题、HTML 和纯文本正文，以及附件和内联图片。收件人取自 SMTP 信封（RCPT TO）。RCPT TO 中的地址如果不在可见的 To 或 Cc 请求头中，则被视为 Bcc。一封邮件的 to、cc 和 bcc 收件人总数最多 50 个，邮件总大小上限为 20 MB。

MIME 消息中没有标准位置的发送选项来自密钥的 SMTP 配置。这些选项包括 IP 池、类别、标签以及打开和点击追踪。未配置的密钥使用组织的默认池、transactional 类别，并启用追踪。在 Email > SMTP 中配置密钥，或调用 SMTP config API。当不同应用需要不同的默认值时，为每个应用分配单独的密钥。更改对新消息立即生效，无需重新连接客户端。

完整会话

在端口 465 上，客户端先建立 TLS 连接，然后在其中运行整个 SMTP 对话：

   ... TLS handshake ...
S: 220 eu1.smtp.bird.com ESMTP Service Ready
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-AUTH PLAIN LOGIN
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: AUTH PLAIN <base64 of bird + key>
S: 235 2.0.0 Authentication succeeded
C: MAIL FROM:<news@yourdomain.com>
C: RCPT TO:<delivered@messagebird.dev>
C: DATA
   ... your MIME message ...
C: .
S: 250 2.0.0 Ok: queued as em_01ky7ma8y2es1s2akzk53tmjn0

在端口 587 或 2525 上，客户端以明文连接，发出 STARTTLS 升级连接，然后在 TLS 内运行相同的对话。升级完成之前不会提供 AUTH：

S: 220 eu1.smtp.bird.com ESMTP Service Ready
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-STARTTLS
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: STARTTLS
S: 220 2.0.0 Ready to start TLS
   ... TLS handshake ...
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-AUTH PLAIN LOGIN
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: AUTH PLAIN <base64 of bird + key>
S: 235 2.0.0 Authentication succeeded
C: MAIL FROM:<news@yourdomain.com>
C: RCPT TO:<delivered@messagebird.dev>
C: DATA
   ... your MIME message ...
C: .
S: 250 2.0.0 Ok: queued as em_01ky7ma8y2es1s2akzk53tmjn0

最终的 250 返回已排队消息的 ID，与你从 API 获得的 em_... ID 相同。你可以在邮件日志中或通过 GET /v1/email/messages/{message_id} 按该 ID 查找消息。

安全重试

管道接受消息后异步投递，而 SMTP 客户端在连接断开时会积极重试。要使重试安全，请在消息中添加 X-Bird-Idempotency-Key 请求头：在保留窗口内重复发送会返回已入队消息的 ID，而不是发送第二份副本。使用对该逻辑消息稳定不变的值，例如订单 ID 或通知 ID。避免为每次尝试生成随机值。

将入队消息 ID 与触发发送的应用事件一起保存。如果连接在收到最终回复之前断开，请使用相同的密钥重试该逻辑消息。保留窗口过后，重试可能会创建另一条消息。请自行保留发送记录，以便在窗口之外进行恢复。

连接限制

每个组织默认最多可保持 10 个并发的已认证 SMTP 连接。连接从认证开始计算，直到关闭为止，涵盖该组织中的所有服务器和 API 密钥。达到上限时，新连接在认证后会收到临时 421 响应。请复用连接、降低并发并重试。该限制独立于消息量，仅计算打开的连接数。Email > SMTP 可查看当前连接数与上限的对比。

根据组织的连接上限调整连接池大小。根据发送配额控制提交速率。HTTP 请求速率限制请求头描述的是 API 请求，而非 SMTP 的发送速率额度。

处理 SMTP 响应

SMTP 会针对未验证的发送域名、保留的收件人域名、不可用的 IP 池、被阻止的附件类型或格式错误的消息返回永久 550 响应。超过 20 MB 上限的消息返回 552。超出发送配额或收件人数超过 50 个会返回临时 452。被屏蔽的收件人异步处理：SMTP 接受消息，然后每个被屏蔽的收件人在邮件日志和事件中显示为 rejected。

关于接口选择，请参阅 SMTP 与 HTTP 的提交和恢复对比。两种路径都在投递给收件人之前将任务入队。email.delivered 事件记录接收服务器的接受情况。该事件不代表邮件已到达收件箱。

后续步骤

• 发送域名：验证你要用于发送的域名。
• 专用 IP 和 IP 池：选择密钥使用哪个池进行发送。
• 屏蔽列表：已接受的收件人为何可能收不到邮件。
• 邮件日志：通过 SMTP 返回的 ID 查找邮件。