Broadcasts
Compose, schedule and send one email to many contacts.
A broadcast is one email sent to many contacts: all of them, a segment, or a topic. Compose it in the dashboard under Broadcasts, with per-contact merge fields, or create it with the API.
Send a broadcast
import { BillionSend } from "@billionsend/node";
const bs = new BillionSend(); // reads 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" });
Leave out scheduled_at to send now. A broadcast needs a verified sending domain in from. You can start from a saved template in the composer.
Lifecycle
draft → scheduled → sending → sent
↘ canceled
↘ failed
- A new broadcast is a draft, and only a draft can be edited.
POST /broadcasts/{id}/sendsends it now or atscheduled_at.POST /broadcasts/{id}/cancelcancels a scheduled broadcast, or one that is already going out. Emails already sent are not recalled. The response’scanceled_remainingsays how many were stopped, andsent_counton a read says how many went out.- Drafts, and failed broadcasts that sent nothing, can be deleted.
- On the API,
scheduledandsendingboth read asqueued. A broadcast readsqueuedwithsent_atempty until its last email has gone out.
Who gets it
Every recipient is checked when the broadcast goes out. Left out are:
- contacts who are
unsubscribedfor the whole team, and contacts who unsubscribed from the broadcast’s sending domain; - contacts who opted out of the broadcast’s topic;
- addresses on the suppression list.
The recipient count the dashboard shows before you send already leaves out these contacts.
The sending domain
The broadcast’s sending domain is the one in its from address, returned as domain_id. It decides:
- Whose unsubscribes apply. People who unsubscribed from this domain are skipped. See Unsubscribes.
- How the recipient sees it. The unsubscribe link opens that domain’s own unsubscribe page, on its own subdomain when it has one.
- Which audience is allowed. A topic or segment bound to another domain is refused with
422, so one brand never mails another brand’s audience.
A domain cannot be deleted while a scheduled or sending broadcast uses it (409).
Merge fields and unsubscribe links
- Per-contact values such as
{{{FIRST_NAME|there}}}are filled in for each recipient. See Templates. - Every broadcast email gets one-click
List-Unsubscribeheaders and a hosted unsubscribe link. To place the link in the body, write{{{UNSUBSCRIBE_URL}}}.
Pacing
A broadcast that fits the capacity available goes out right away. A larger one goes out in waves over the next days. Transactional email is never held behind a broadcast: it is sent ahead of a broadcast’s remaining recipients.
The send call tells you what to expect:
{
"id": "8c1f0b8e-…",
"finishes_at": "2026-09-18T13:26:05Z",
"estimated": true,
"warning": { "code": "paced", "days": 3, "message": "…" }
}
finishes_atis the estimated time the last email goes out. It is an estimate, and other sends can move it.warningappears when sending takes more than one wave:pacedwhen the audience is larger than the capacity available now,queued_behindwhen other sends come first.- While it goes out,
GET /broadcasts/{id}carries a livefinishes_atandsent_count. - An audience that would need more than 24 days of capacity is refused with
422 broadcast_too_large. Split it into smaller segments.
Duplicate a broadcast
POST /broadcasts/{id}/duplicate copies any broadcast, even a sent or failed one, into a new draft. In the dashboard, use Duplicate in the broadcast’s menu.
- Copied: segment, topic, sender, subject,
reply_to, preview text and content. - Not copied: the schedule, the counts and the delivery progress. The copy is a normal draft.
- The name is the original’s followed by
(copy).
When a broadcast fails
A broadcast ends failed when it was accepted but cannot go out, or when sending kept failing. GET /broadcasts/{id} then returns failure_reason and failed_at. Emails already handed over stay sent, and the team’s owners get an email once.
failure_reason |
Meaning |
|---|---|
domain_missing |
The sending domain was deleted. |
sender_domain_mismatch |
from is no longer on the domain the broadcast was scheduled with. |
topic_other_domain |
The topic is bound to another domain. |
segment_other_domain |
The segment is bound to another domain. |
domain_unverified |
The sending domain stayed unverified for a few hours of retries. |
retries_exhausted |
Another error kept failing until the retries ran out. |
To reach the audience, duplicate the broadcast, fix the cause in the new draft, and send it.
When a broadcast is refused
403 sending_paused: your bounce or complaint rate is too high. See Sending limits.403 broadcasts_paused: broadcasts are paused, either platform-wide while rates recover or for your team by BillionSend. Transactional email is not affected.403 inbox_send_policy: the sender is on your shared inbox domain, which cannot send broadcasts.
When a broadcast reaches your plan’s volume, the rest of its audience waits and goes out when there is room. See Plans and limits.
See the API reference for every broadcast endpoint.