跳到内容
Esc
↑↓导航↵打开⌘J预览
本页内容

邮件群发

向大量联系人撰写、定时并发送同一封邮件群发,支持合并字段、发送节奏,以及按域名区分的退订链接。

群发是把同一封邮件发给多位联系人:全部联系人、某个 分群 或某个 订阅主题。在控制台的 群发 页面撰写,可使用按联系人填充的合并字段,也可以通过 API 创建。

发送邮件群发

import { BillionSend } from "@billionsend/node";

const bs = new BillionSend(); // 读取 BILLIONSEND_API_KEY

const { data, error } = await bs.broadcasts.create({
  name: "November news",
  segment_id: "SEGMENT_ID",
  from: "Acme <news@mail.example.com>",
  subject: "What's new",
  html: "<p>Hi {{{FIRST_NAME|there}}},</p><p>...</p><p><a href=\"{{{UNSUBSCRIBE_URL}}}\">Unsubscribe</a></p>",
});

if (error) throw error;

await bs.broadcasts.send(data.id, { scheduled_at: "in 1 hour" });

不传 scheduled_at 即立即发送。群发需要在 from 中使用已验证的发信域名。在编辑器里可以从已保存的 模板 开始。

生命周期

draft → scheduled → sending → sent
              ↘ canceled
              ↘ failed
  • 新建的群发是 草稿(draft),只有草稿可以编辑。
  • POST /broadcasts/{id}/send 立即发送,或在 scheduled_at 指定的时间发送。
  • POST /broadcasts/{id}/cancel 取消已定时的群发,或正在发出的群发。已经发出的邮件不会被召回。响应中的 canceled_remaining 表示被停止的数量,读取时的 sent_count 表示已发出的数量。
  • 草稿,以及没有发出任何邮件的失败群发,可以删除。
  • 在 API 中,scheduled 和 sending 都显示为 queued。在最后一封邮件发出之前,群发显示为 queued,且 sent_at 为空。

谁会收到

群发发出时会逐个检查收件人。以下收件人会被排除:

  • 对整个团队设置为 unsubscribed 的联系人,以及已从该群发的发信域名退订的联系人;
  • 已退出该群发订阅主题的联系人;
  • 位于 抑制列表 中的地址。

发送前,控制台显示的收件人数量已经排除了这些联系人。

发信域名

群发的发信域名是 from 地址中的域名,在响应中以 domain_id 返回。它决定:

  • 适用谁的退订。 已从该域名退订的人会被跳过。参见 退订。
  • 收件人看到什么。 退订链接会打开该域名自己的 退订页面;如果该域名有自己的子域名,页面就在这个子域名上。
  • 允许发给哪些受众。 绑定到其他域名的订阅主题或分群会被拒绝,返回 422,这样一个品牌不会给另一个品牌的受众发邮件。

只要有已定时或正在发送的群发使用某个域名,该域名就不能删除(409)。

合并字段与退订链接

  • 按联系人填充的值,例如 {{{FIRST_NAME|there}}},会为每位收件人分别填入。参见 模板。
  • 每封群发邮件都带有一键式 List-Unsubscribe 头和托管的退订链接。要把链接放进正文,写 {{{UNSUBSCRIBE_URL}}}。

发送节奏

容量足够的群发会立即发出。较大的群发会在接下来几天里分批发出。事务邮件不会被群发堵住:它会排在群发剩余收件人之前发送。

发送调用会告诉你预期情况:

{
  "id": "8c1f0b8e-…",
  "finishes_at": "2026-09-18T13:26:05Z",
  "estimated": true,
  "warning": { "code": "paced", "days": 3, "message": "…" }
}
  • finishes_at 是最后一封邮件发出的预计时间。这只是估计值,其他发送任务可能使它推迟。
  • 发送需要分多批时会出现 warning:受众超过当前可用容量时为 paced,有其他发送任务排在前面时为 queued_behind。
  • 发送过程中,GET /broadcasts/{id} 会返回实时的 finishes_at 和 sent_count。
  • 需要超过 24 天容量的受众会被拒绝,返回 422 broadcast_too_large。请拆成更小的分群。

复制群发

POST /broadcasts/{id}/duplicate 可以把任何群发(包括已发送或已失败的)复制为新的草稿。在控制台中,使用该群发菜单里的 创建副本。

  • 会复制: 分群、订阅主题、发件人、主题行、reply_to、预览文本和内容。
  • 不会复制: 发送计划、各项计数和投递进度。复制出的是一份普通草稿。
  • 名称是原名称后面加 (copy)。

群发失败时

群发已被接受但无法发出,或者发送一直失败时,状态变为 failed。此时 GET /broadcasts/{id} 会返回 failure_reason 和 failed_at。已经交出的邮件保持已发送状态,团队所有者会收到一封邮件通知,只通知一次。

failure_reason 含义
domain_missing 发信域名已被删除。
sender_domain_mismatch from 不再属于该群发定时时所用的域名。
topic_other_domain 订阅主题绑定到了其他域名。
segment_other_domain 分群绑定到了其他域名。
domain_unverified 发信域名在数小时的重试中始终未验证。
retries_exhausted 其他错误持续失败,直到重试次数用完。

要触达这批受众,复制该群发,在新草稿中修复原因,然后发送。

群发被拒绝时

  • 403 sending_paused:你的退信率或投诉率过高。参见 发送限制。
  • 403 broadcasts_paused:群发已暂停,原因可能是平台在指标恢复期间整体暂停,也可能是 BillionSend 对你的团队暂停。事务邮件不受影响。
  • 403 inbox_send_policy:发件人使用的是你的共享收件箱域名,该域名不能发送群发。

群发达到套餐的发送量上限后,剩余受众会等待,有空余额度时再发出。参见 套餐与限额。

所有群发接口请参见 API 参考。

这个页面有帮助吗?