---
title: 群發電子報
description: 撰寫、排程並把同一封電子報寄給大量聯絡人，支援合併欄位、寄送節奏，以及依網域區分的退訂連結。
seo:
  title: 電子報群發與排程
ai:
  exclude: true
---

群發就是把同一封電子報寄給多位聯絡人：全部聯絡人、某個[分群](/docs/zh-hant/concepts/segments)，或某個[訂閱主題](/docs/zh-hant/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-hant/concepts/templates)開始。

## 生命週期

```
draft → scheduled → sending → sent
              ↘ canceled
              ↘ failed
```

- 新建立的群發是**草稿**（`draft`），只有草稿可以編輯。
- `POST /broadcasts/{id}/send` 會立即傳送，或在 `scheduled_at` 指定的時間傳送。
- `POST /broadcasts/{id}/cancel` 可取消已排程的群發，或已經開始寄出的群發。已寄出的 Email 無法收回。回應中的 `canceled_remaining` 表示有多少封被停止，讀取時的 `sent_count` 表示已寄出多少封。
- 草稿，以及一封都沒寄出的失敗群發，可以刪除。
- 在 API 中，`scheduled` 與 `sending` 都顯示為 `queued`。在最後一封 Email 寄出之前，群發會維持 `queued`，且 `sent_at` 為空。

## 誰會收到

群發寄出時會逐一檢查每位收件者。以下對象會被排除：

- 對整個團隊設為 `unsubscribed` 的聯絡人，以及已退訂該群發寄件網域的聯絡人；
- 已退訂該群發訂閱主題的聯絡人；
- 在[抑制清單](/docs/zh-hant/concepts/suppressions)上的位址。

控制台在寄出前顯示的收件者數量，已經排除了這些聯絡人。

## 寄件網域

群發的寄件網域就是 `from` 位址中的網域，在回應中以 `domain_id` 表示。它決定：

- **套用誰的退訂。** 已退訂這個網域的人會被略過。請見[退訂](/docs/zh-hant/concepts/unsubscribes)。
- **收件者看到的樣子。** 退訂連結會開啟該網域專屬的[退訂頁面](/docs/zh-hant/concepts/unsubscribes)；網域設有自己的子網域時，頁面就在該子網域上。
- **允許哪些受眾。** 綁定到其他網域的訂閱主題或分群會被拒絕，回傳 `422`，因此一個品牌不會寄給另一個品牌的受眾。

有已排程或寄送中的群發使用某個網域時，該網域無法刪除（`409`）。

## 合併欄位與退訂連結

- `{{{FIRST_NAME|there}}}` 這類依聯絡人而異的值，會為每位收件者各自帶入。請見[範本](/docs/zh-hant/concepts/templates)。
- 每封群發 Email 都會加上一鍵退訂的 `List-Unsubscribe` 標頭與託管的退訂連結。要把連結放進內文，請寫 `{{{UNSUBSCRIBE_URL}}}`。

## 寄送節奏

在目前可用額度內寄得完的群發，會立即寄出。較大的群發會在接下來幾天分批寄出。交易郵件不會被群發卡住：它會排在群發剩餘收件者之前寄出。

傳送呼叫的回應會告訴你預期的結果：

```json
{
  "id": "8c1f0b8e-…",
  "finishes_at": "2026-09-18T13:26:05Z",
  "estimated": true,
  "warning": { "code": "paced", "days": 3, "message": "…" }
}
```

- `finishes_at` 是最後一封 Email 預計寄出的時間。這只是估計，其他寄送可能讓它改變。
- 寄送需要不只一批時會出現 `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`。已交出的 Email 維持已寄出，團隊的擁有者會收到一次通知信。

| `failure_reason` | 意義 |
| --- | --- |
| `domain_missing` | 寄件網域已被刪除。 |
| `sender_domain_mismatch` | `from` 已不在排程時使用的網域上。 |
| `topic_other_domain` | 訂閱主題綁定到其他網域。 |
| `segment_other_domain` | 分群綁定到其他網域。 |
| `domain_unverified` | 寄件網域在幾個小時的重試期間一直沒有通過驗證。 |
| `retries_exhausted` | 另一種錯誤一再發生，直到重試次數用完。 |

要寄給這批受眾，請複製這個群發，在新草稿中修正原因，再傳送。

## 群發被拒絕時

- `403 sending_paused`：你的退信率或投訴率過高。請見[寄送限制](/docs/zh-hant/concepts/sending-limits)。
- `403 broadcasts_paused`：群發已暫停，原因可能是平台在比率恢復前整體暫停，也可能是 BillionSend 針對你的團隊暫停。交易郵件不受影響。
- `403 inbox_send_policy`：寄件人使用的是你的共用收件匣網域，這種網域不能寄送群發。

群發達到方案的用量上限時，剩餘的受眾會等待，有空間時再寄出。請見[方案與限制](/docs/zh-hant/billing)。

所有群發端點請見 [API 參考](/docs/zh-hant/api-reference)。
