Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

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}/send sends it now or at scheduled_at.
  • POST /broadcasts/{id}/cancel cancels a scheduled broadcast, or one that is already going out. Emails already sent are not recalled. The response’s canceled_remaining says how many were stopped, and sent_count on a read says how many went out.
  • Drafts, and failed broadcasts that sent nothing, can be deleted.
  • On the API, scheduled and sending both read as queued. A broadcast reads queued with sent_at empty 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 unsubscribed for 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).

  • Per-contact values such as {{{FIRST_NAME|there}}} are filled in for each recipient. See Templates.
  • Every broadcast email gets one-click List-Unsubscribe headers 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_at is the estimated time the last email goes out. It is an estimate, and other sends can move it.
  • warning appears when sending takes more than one wave: paced when the audience is larger than the capacity available now, queued_behind when other sends come first.
  • While it goes out, GET /broadcasts/{id} carries a live finishes_at and sent_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.

Was this page helpful?