---
title: Broadcasts
description: Compose, schedule and send one email to many contacts.
---

A broadcast is one email sent to many contacts: all of them, a [segment](/docs/concepts/segments), or a [topic](/docs/concepts/topics). Compose it in the dashboard under **Broadcasts**, with per-contact merge fields, or create it with the API.

## Send a broadcast

```ts
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](/docs/concepts/templates) 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](/docs/concepts/suppressions).

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](/docs/concepts/unsubscribes).
- **How the recipient sees it.** The unsubscribe link opens that domain's own [unsubscribe page](/docs/concepts/unsubscribes), 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](/docs/concepts/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:

```json
{
  "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](/docs/concepts/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](/docs/billing).

See the [API reference](/docs/api-reference) for every broadcast endpoint.
