群發電子報
撰寫、排程並把同一封電子報寄給大量聯絡人,支援合併欄位、寄送節奏,以及依網域區分的退訂連結。
群發就是把同一封電子報寄給多位聯絡人:全部聯絡人、某個分群,或某個訂閱主題。在控制台的群發頁面撰寫,可使用依聯絡人帶入的合併欄位,也可以透過 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可取消已排程的群發,或已經開始寄出的群發。已寄出的 Email 無法收回。回應中的canceled_remaining表示有多少封被停止,讀取時的sent_count表示已寄出多少封。- 草稿,以及一封都沒寄出的失敗群發,可以刪除。
- 在 API 中,
scheduled與sending都顯示為queued。在最後一封 Email 寄出之前,群發會維持queued,且sent_at為空。
誰會收到
群發寄出時會逐一檢查每位收件者。以下對象會被排除:
- 對整個團隊設為
unsubscribed的聯絡人,以及已退訂該群發寄件網域的聯絡人; - 已退訂該群發訂閱主題的聯絡人;
- 在抑制清單上的位址。
控制台在寄出前顯示的收件者數量,已經排除了這些聯絡人。
寄件網域
群發的寄件網域就是 from 位址中的網域,在回應中以 domain_id 表示。它決定:
- 套用誰的退訂。 已退訂這個網域的人會被略過。請見退訂。
- 收件者看到的樣子。 退訂連結會開啟該網域專屬的退訂頁面;網域設有自己的子網域時,頁面就在該子網域上。
- 允許哪些受眾。 綁定到其他網域的訂閱主題或分群會被拒絕,回傳
422,因此一個品牌不會寄給另一個品牌的受眾。
有已排程或寄送中的群發使用某個網域時,該網域無法刪除(409)。
合併欄位與退訂連結
{{{FIRST_NAME|there}}}這類依聯絡人而異的值,會為每位收件者各自帶入。請見範本。- 每封群發 Email 都會加上一鍵退訂的
List-Unsubscribe標頭與託管的退訂連結。要把連結放進內文,請寫{{{UNSUBSCRIBE_URL}}}。
寄送節奏
在目前可用額度內寄得完的群發,會立即寄出。較大的群發會在接下來幾天分批寄出。交易郵件不會被群發卡住:它會排在群發剩餘收件者之前寄出。
傳送呼叫的回應會告訴你預期的結果:
{
"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:你的退信率或投訴率過高。請見寄送限制。403 broadcasts_paused:群發已暫停,原因可能是平台在比率恢復前整體暫停,也可能是 BillionSend 針對你的團隊暫停。交易郵件不受影響。403 inbox_send_policy:寄件人使用的是你的共用收件匣網域,這種網域不能寄送群發。
群發達到方案的用量上限時,剩餘的受眾會等待,有空間時再寄出。請見方案與限制。
所有群發端點請見 API 參考。