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

群发是把同一封邮件发给多位联系人：全部联系人、某个 [分群](/docs/zh-hans/concepts/segments) 或某个 [订阅主题](/docs/zh-hans/concepts/topics)。在控制台的 **群发** 页面撰写，可使用按联系人填充的合并字段，也可以通过 API 创建。

## 发送邮件群发

```ts
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` 中使用已验证的发信域名。在编辑器里可以从已保存的 [模板](/docs/zh-hans/concepts/templates) 开始。

## 生命周期

```
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` 的联系人，以及已从该群发的发信域名退订的联系人；
- 已退出该群发订阅主题的联系人；
- 位于 [抑制列表](/docs/zh-hans/concepts/suppressions) 中的地址。

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

## 发信域名

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

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

只要有已定时或正在发送的群发使用某个域名，该域名就不能删除（`409`）。

## 合并字段与退订链接

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

## 发送节奏

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

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

```json
{
  "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`：你的退信率或投诉率过高。参见 [发送限制](/docs/zh-hans/concepts/sending-limits)。
- `403 broadcasts_paused`：群发已暂停，原因可能是平台在指标恢复期间整体暂停，也可能是 BillionSend 对你的团队暂停。事务邮件不受影响。
- `403 inbox_send_policy`：发件人使用的是你的共享收件箱域名，该域名不能发送群发。

群发达到套餐的发送量上限后，剩余受众会等待，有空余额度时再发出。参见 [套餐与限额](/docs/zh-hans/billing)。

所有群发接口请参见 [API 参考](/docs/zh-hans/api-reference)。
