文档
Sign inGet started
立即开始
指南
API 参考
SDK
CLI
知识库
更新日志

通过 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 响应，指明应使用的主机。
区域主机
EUeu1.smtp.bird.com
USus1.smtp.bird.com
端口加密方式
465隐式 TLS (SMTPS)
587STARTTLS
2525STARTTLS
选择你的客户端支持的方式：
  • 端口 465，隐式 TLS (SMTPS)。 连接从第一个字节起即加密，在发送任何命令之前。在大多数库中对应的是 "SSL/TLS" 或 "SMTPS" 选项。
  • 端口 587 和 2525，STARTTLS。 连接以明文方式打开，然后在身份验证之前通过 STARTTLS 命令升级为 TLS。对应的是 "STARTTLS" 选项，有时简单标记为 "TLS"。如果你的网络屏蔽了 587，请使用 2525。
无论哪种方式，会话在发送凭据之前都已加密，因此凭据不会以明文传输：在 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 相同。你可以通过该 ID 在邮件日志或 GET /v1/email/messages/{message_id} 中查找该消息。

安全重试

管道接受消息后异步投递，而 SMTP 客户端在连接中断时会激进重试。为确保重试安全，请在消息中添加 X-Bird-Idempotency-Key 请求头：在保留窗口内的重复请求会返回已排队消息的 ID，而不是发送第二封副本。使用对逻辑消息稳定的值，例如订单 ID 或通知 ID。避免为每次尝试生成随机值。
将已排队消息的 ID 与触发发送的应用事件一起保存。如果连接在你收到最终回复之前中断，请使用相同的密钥重试该逻辑消息。保留窗口过后，重试可能会创建另一封消息。请维护你自己的发送记录，以便在窗口过期后进行恢复。

连接限制

每个组织默认最多可保持 10 个并发的已认证 SMTP 连接。连接从认证开始计算直到关闭，涵盖组织内的所有服务器和 API 密钥。达到限制后，新连接在认证后会收到瞬态 421 响应。请复用连接、降低并发并重试。该限制计算的是打开的连接数，与消息量无关。Email > SMTP 显示当前连接数与限制的对比。
根据组织的连接上限调整你的连接池大小。按照发送配额控制提交速度。HTTP 速率限制请求头描述的是 API 请求，不是 SMTP 发送速率配额。

处理 SMTP 响应

SMTP 以永久 550 响应报告未验证的发送域名、保留的收件人域名、不可用的 IP 池、被阻止的附件类型或格式错误的消息。超过 20 MB 上限的消息返回 552。超出发送配额或收件人数超过 50 时返回瞬态 452。被抑制的收件人异步处理：SMTP 接受消息，然后每个被抑制的收件人在邮件日志和事件中显示为 rejected。
关于接口选择，请比较 SMTP 与 HTTP 的提交和恢复。两种方式都在投递给收件人之前排队处理。email.delivered 事件记录接收服务器的接受状态，但该事件并不意味着邮件已到达收件箱。

后续步骤

相关资源

继续查阅此主题的文档、指南和示例。资源为英文。

探索功能SMTP relay