工程实践

事务性邮件 API 生产环境检查清单

一份面向上线事务性邮件系统的工程师的技术指南,涵盖 DNS 验证、幂等性、错误处理以及生产就绪所需的成本分析。

事务性邮件的生产就绪

要上线事务性邮件 API,您必须验证三个不同的层面:服务商受理(API 接受您的请求)、投递(收件服务器接受邮件)和进入收件箱(邮件到达用户手中)。一个可用于生产环境的系统需要:已验证的 DNS 记录、防止重复发送的健壮幂等策略、针对投递事件的完善 Webhook 处理,以及能随发送量扩展的成本模型。其中任何一环出问题,都可能导致数据丢失或信誉受损。

1. 域名与 DNS 验证

从未经验证的域名发送邮件,必然会触发垃圾邮件过滤器,或被收件方 MTA(Mail Transfer Agent,邮件传输代理)直接拒收。您必须证明自己拥有发信域名。

必备三件套:SPF、DKIM 和 DMARC

  • SPF(Sender Policy Framework,发件人策略框架):一条 DNS 记录,列出哪些 IP 地址或服务被授权代表您的域名发送邮件。没有它,收件方就无法判断发件人是否在伪造您的域名。更多详情请参阅我们的 SPF 术语表词条。
  • DKIM(DomainKeys Identified Mail,域名密钥识别邮件):在邮件头中添加加密签名,确保内容在传输过程中未被篡改。
  • DMARC(Domain-based Message Authentication, Reporting, and Conformance,基于域名的邮件身份验证、报告与一致性):告诉收件方在 SPF 或 DKIM 未通过时应如何处理(none、quarantine 或 reject)。

在正式切换到生产环境之前,请使用 SendHQ 邮件 DNS 检查工具等工具,确认这些记录已正确传播。详细的操作步骤请参阅我们的 DKIM、SPF 和 DMARC 指南。

验证清单

  • SPF 记录包含所有发信来源。
  • DKIM 公钥已发布到 DNS,且与 API 使用的私钥匹配。
  • DMARC 策略已设置(先用 p=none 监控,然后迁移至 p=reject)。
  • 已为您的发信 IP 配置反向 DNS(rDNS)(若使用独享 IP)。

2. API 集成与可靠性

事务性邮件属于关键路径事件(密码重置、发票、双因素认证)。把邮件 API 当作“发出去就不管”的 HTTP 调用,迟早会酿成生产事故。

幂等与防重复

网络超时不可避免。如果您的应用向邮件 API 发送了请求,但连接在响应返回之前断开,您的重试逻辑就可能把同一封邮件发送两次。这对 AI 智能体或自动化工作流来说尤其危险。

请在请求头中加入幂等键。这样,如果在特定时间窗口内两次发送同一个 key,服务商会返回最初的成功响应,而不会发送第二封邮件。

{
  "idempotency_key": "req_88234abc123",
  "to": "user@example.com",
  "template_id": "welcome_email",
  "variables": {
    "name": "Alice"
  }
}

处理 AI 智能体与 A2A 通信

与 AI 智能体集成时(通过 MCP 服务器或类似方式),您必须把邮件视为外部副作用。智能体可能陷入循环,也可能因幻觉而误触发。在没有以下任一措施的情况下,切勿允许智能体触发生产环境的发送:

  1. 人工介入(HITL):在您的界面中加入人工审批步骤。
  2. 严格的速率限制:按用户或按智能体设置配额,防止意外滥发。
  3. 模板约束:强制智能体使用只能修改变量的托管模板,防止智能体编写任意(且可能有害)的内容。

3. 错误处理与可观测性

您的系统必须区分暂时性错误(可重试)和永久性错误(不可重试)。

错误分类

Error TypeExampleAction
Transient429 Too Many Requests, 503 Service UnavailableExponential backoff retry
Permanent400 Bad Request (Invalid Email), 401 UnauthorizedLog error, alert developer, do not retry
Delivery550 User Unknown, 554 Message RejectedUpdate suppression list, notify user

Webhook 集成

API 响应只能告诉您服务商是否受理了邮件。要知道邮件是否已送达,您需要 Webhook。建议在数据库中跟踪以下事件:

  • Sent:服务商已将邮件交给 MTA。
  • Delivered:收件服务器已接受邮件。
  • Bounced:收件服务器拒收了邮件(硬退信 = 永久性,软退信 = 暂时性)。
  • Complained:用户将邮件标记为垃圾邮件。

投递事件的 Webhook 请求体示例:

{
  "event": "delivered",
  "message_id": "msg_12345",
  "timestamp": "2026-09-15T10:00:00Z",
  "recipient": "user@example.com"
}

4. 成本分析与服务商取舍

选择服务商,是在开发者体验(DX)、成本和基础设施负担之间做取舍。根据 2026 年 9 月的价格数据,成本差异相当大。

服务商价格对比

  • Amazon SES:大发送量下成本最低的选择。按量计费为每 1,000 封邮件 0.10 USD(Amazon SES 价格)。新的分级套餐(2026 年 7 月 21 日)包括 Essentials(0.16 USD/1k)、Pro(0.22 USD/1k + 105 USD/月/区域)和 Enterprise(0.23 USD/1k + 500 USD/月)。
  • Resend:专注于开发者体验。免费套餐为每月 3,000 封邮件(每天上限 100 封)。Pro 套餐为每月 20 USD,含 50,000 封邮件,超出部分每 1,000 封 0.90 USD(Resend 价格)。
  • SendGrid:Essentials 起价为每月 19.95 USD。免费套餐现已改为 60 天试用(SendGrid 价格)。
  • Mailgun:每月 15 USD,含 10,000 封邮件,超出部分每 1,000 封 1.80 到 1.10 USD 不等(Mailgun 价格)。
  • Postmark:每月 15 USD,含 10,000 封邮件,超出部分每 1,000 封 1.80 到 1.20 USD 不等(Postmark 价格)。

“规模差距”

以发送 50,000 封事务性邮件为例。在 Amazon SES 按量计费下,费用大约为 5 USD;而按 Postmark 的分级价格,同样的发送量大约需要 66 USD。对大多数初创公司来说,专门化 API 带来的开发者体验值得这份溢价;但对于大发送量的 AI 智能体,SES 模式往往是必需的。

5. 最终上线清单

在部署到生产环境之前,请逐项完成以下最终检查:

基础设施

  • DNS 记录(SPF、DKIM、DMARC)已验证且处于活动状态。
  • API 密钥限定于工作区作用域并存储在安全密钥库中(而非代码中)。
  • Webhook 端点公开、安全,且能处理并发流量突发。

逻辑

  • 所有发送请求均已实现幂等键。
  • 重试逻辑对 429 和 5xx 错误采用指数退避。
  • 已处理抑制列表(不要尝试向硬退信地址重新发送)。
  • AI 智能体触发器具备人工审批步骤或严格的速率限制。

监控

  • 已为 4xx/5xx API 响应激增设置告警。
  • 控制台跟踪投递率与退信率。
  • 遥测数据遵循隐私最小化原则并符合地区法律(例如仅限 EU 存储)。

总结

事务性邮件是一种副作用,很容易破坏应用的可靠性或域名的信誉。将服务商受理与投递区分开来,并专注于幂等和 DNS 验证,您就能构建一个能够抵御网络故障和服务商中断的系统。如果您的团队需要一种更简洁的方式来实现基于已验证域名的发送和面向智能体的基础设施,欢迎访问 https://sendhq.cc 了解相关功能。