发送单封与批量邮件

单封接口用于提交一封邮件；批量接口用于在一个请求中提交多封相互独立的邮件。两个接口均采用异步处理：平台先返回受理结果，再逐封完成投递。

选择发送方式

新接入可使用以下接口：

邮件用途

每封邮件都应声明真实用途：

非模板邮件省略 messageType 时默认为 MARKETING。不要把营销内容标记为事务邮件以绕过收件人或退订规则。

选择正文或模板

直接提供正文

• text 和 html 至少提供一项，也可以同时提供。
• 同时提供纯文本和 HTML 有助于兼容不同邮件客户端。
• 直接正文不会执行 variables 替换，应由调用方在提交前完成渲染。

使用模板

• 提供 template.templateId，并省略非空的 text 和 html。
• subject 仍然必填，并支持模板变量。
• 模板必须审核通过、内容校验通过并处于启用状态。

详见使用模板和变量。当前接口没有可用的附件内容上传和投递能力，请省略 attachments。

发送单封邮件

发送批量邮件

批量请求的 messages 数组包含 1–100 个邮件对象，每项结构与单封发送一致：

{
  "messages": [
    {
      "from": {"email": "news@example.com"},
      "to": [{"email": "alice@example.net"}],
      "subject": "Product update",
      "html": "<p>Hello Alice</p>",
      "messageType": "MARKETING"
    },
    {
      "from": {"email": "news@example.com"},
      "to": [{"email": "bob@example.net"}],
      "subject": "Product update",
      "html": "<p>Hello Bob</p>",
      "messageType": "MARKETING"
    }
  ]
}

成功响应返回批次标识和逐封结果：

• batchId：本次批量任务标识；
• acceptedCount：成功受理的邮件对象数，不是送达人数；
• messages[].index：对应输入数组下标；
• messages[].messageId：用于逐封查询最终结果。

批量处理语义

受理前：整批校验

平台会校验批量大小、每封邮件的字段、邮件用途、模板可用性和当前额度。任一子项校验失败时，整批拒绝，不受理任何子项。

批量限流按邮件对象数计数。例如，一次包含 20 个子项的请求消耗 20 个发送单位，而不是 1 次 HTTP 请求。

受理后：逐封处理

整批受理后，每封邮件独立检查发件身份、模板、抑制名单和发送通道，因此同一批次可以同时出现已送达、已退信、已拒绝和发送失败。

无效收件人

同一邮件对象内，To、Cc 和 Bcc 按忽略大小写去重。事务邮件存在部分格式错误地址但仍有有效收件人时，响应可返回 invalidRecipients 预检查明细。

该字段只反映地址格式检查，不代表完整的最终失败列表。邮箱不存在、退信、投诉和抑制需要通过后续状态判断。

幂等与重试

• 幂等键最长 128 个字符。
• 同一 AppID、同一接口、相同键和相同请求体会返回首次受理结果，不重复发送。
• 相同键对应不同内容时返回冲突。
• 单封与批量接口使用独立的幂等命名空间。
• 默认保留窗口为 24 小时，实际以接入环境为准；业务系统仍需长期保存发送记录。
• 使用 CheckSum 鉴权时，每次 HTTP 尝试重新生成 Nonce、CurTime 和 CheckSum，但保持幂等键和请求体不变。

常见问题

批量中某一封失败会影响其他邮件吗？

受理前任一子项校验失败会整批拒绝；受理后每封独立处理，最终结果可能不同。请按每封 Message ID 查询。

超时后如何重试？

保持原幂等键、原请求体及批量顺序，先核对原任务；使用 CheckSum 时为每次 HTTP 尝试重新生成 Nonce、CurTime 和签名。

相关资源