邮件群发
向大量联系人撰写、定时并发送同一封邮件群发,支持合并字段、发送节奏,以及按域名区分的退订链接。
群发是把同一封邮件发给多位联系人:全部联系人、某个 分群 或某个 订阅主题。在控制台的 群发 页面撰写,可使用按联系人填充的合并字段,也可以通过 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 参考。