Sign inGet Started

批量发送

POST /v1/email/batches 在一个请求中接受最多 100 个完整的发送载荷,即通过一次调用发送多条独立消息的批量邮件模式。每个条目都有自己的发件人、收件人和内容。使用批量发送可以用更少的 API 请求提交收据、提醒或其他按收件人区分的消息。如果只发送一条消息,请参阅发送邮件。

何时使用哪种方式

  • 手头已有的独立消息。 使用批量发送,一个请求全部提交。
  • 持续的大批量消息流。 在循环中调用单条发送端点是一种合理的架构,批量发送不会降低单条消息的投递成本,也不会加快投递速度。它改变的是吞吐量,因为批量请求使用 email_batch 请求速率限制策略,而非 email_send 策略,且每个请求最多可包含 100 条消息。
  • 向已存储的受众发送一封邮件。 这属于广播,它会将受众解析为收件人,并按联系人进行个性化。

批量发送中的模板

每个条目都可以使用已发布的 template,并带有自己的 parameters 和 language。

使用联系人属性的模板会针对每个 To 地址分别进行个性化,使用同一工作区中的联系人。Cc 和 Bcc 会收到每个 To 收件人个性化邮件的副本,无需匹配的联系人。批次会对重复地址共享查询,并读取每个模板用到的属性。如果所选语言和请求信封不引用联系人,则不会增加联系人查询。

收件人的值在批次被接受时保存,定时条目也是如此。之后编辑联系人或回退值不会改变已排队的消息。如果缺少 To 联系人、缺少必需参数、联系人匹配不唯一或联系人值无效,批次会在任何条目被接纳之前被拒绝。数据库故障会返回可重试的错误,而不会将联系人视为缺失。有关缺失值和回退规则,请参阅模板个性化。

批量发送

请求体是一个 JSON 对象,其 messages 数组包含 1 到 100 个消息对象。每个条目是一个完整、独立的发送请求,拥有自己的 from、to、subject、内容,以及可选的 category、ip_pool_id、标签和元数据。条目的 schema 与单条发送的载荷完全相同,因此发送邮件中的所有内容均按条目适用,包括 category 默认值 marketing 以及通过模板发送。

这包括 scheduled_at,因此一个批次可以混合立即发送和稍后发送的消息,每条消息按各自的时间发出。定时发送中的规则和配额按条目适用,定时条目通过其自身的 ID 取消,与其他定时消息一样。

const batch = await bird.email.sendBatch({
  messages: [
    {
      from: { email: "onboarding@messagebird.dev", name: "Bird" },
      to: ["alice@example.com"],
      subject: "Your receipt",
      html: "<p>Thanks, Alice.</p>",
    },
    {
      from: { email: "onboarding@messagebird.dev", name: "Bird" },
      to: ["bob@example.com"],
      subject: "Your receipt",
      html: "<p>Thanks, Bob.</p>",
    },
  ],
});
for (const item of batch.data) console.log(item.id, item.status);

全有或全无的验证

所有条目在任何条目入队之前都会被验证。如果某条消息未通过验证(字段级验证错误或未验证的发件人域),整个批次将被拒绝并返回 422,不会发送任何消息:修复该条目后重新提交批次。

屏蔽不属于该检查的范围。即使某条目的所有收件人都被屏蔽,该条目仍会被接受并获得自己的 em_ ID,这些收件人会在消息处理后以 status: rejected 的形式返回(参见屏蔽列表)。

处理 202 响应

成功的批量请求返回 202 Accepted,按提交顺序每条消息对应一个条目:

代码示例
{
  "data": [
    { "id": "em_01ky7q1vmkerwa7fxyycfe5ks1", "status": "accepted", "category": "transactional" },
    { "id": "em_01ky7q1vmkesr9h1y52tkqng9f", "status": "accepted", "category": "marketing" },
    { "id": "em_01ky7q1vmkesyr1z1h4s48jjxm", "status": "accepted", "category": "transactional" }
  ]
}

每个子消息都是一条普通消息:通过其 em_ ID 在 GET /v1/email/messages/{message_id}、收件人和事件端点以及 webhook 中跟踪它,与单独发送时完全一样。同样的异步模型适用,因此 202 表示已被持久接受,按收件人的结果随后送达。

幂等重试

幂等性是可选的。SDK 会为自动重试生成键。对于不同调用之间的重试,或直接使用 HTTP 的情况,请参阅幂等性指南,了解键的复用方式和重放限制。

附件与请求体上限

每个批次条目可以有自己的 attachments,字段约定和单条消息大小预算与单条发送相同(参见附件)。批次整体还有一个额外限制:序列化后的 JSON 请求体上限为 20 MB,超出此大小的请求体将被拒绝并返回 413。Base64 编码的附件计入该上限,因此附件较多的批次会很快达到上限。将它们拆分到多个批次中,或逐条发送。

广播

广播向已存储的受众发送一封邮件。发送开始时,我们会将受众的当前成员(排除屏蔽列表中的成员)解析为收件人列表,每个收件人的联系人属性会填充模板的变量。可以通过控制面板、/v1/email/broadcasts 或 bird email broadcasts 命令发起广播。广播提供了完整的操作指南。

后续步骤

  • 发送邮件:完整的条目载荷,包括字段、限制以及标签与元数据的区别
  • 广播:向已存储的受众发送一封邮件,按联系人个性化
  • 类别:marketing 和 transactional,以及各自对屏蔽策略的影响
  • 幂等性:键格式、保留时间和重放语义
  • API 参考:完整的批量请求和响应 schema
  • 一次 API 调用发送 100 封邮件:一段视频,展示批量发送的过程以及每条消息如何报告状态

继续查看此主题的文档、指南和示例。