> ## Documentation Index
> Fetch the complete documentation index at: https://nuntly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and send a broadcast

> Create a broadcast, send it now or later, and follow it through its statuses, its recipients, and the email events of each message.

A broadcast sends one template to your contacts, or to one segment of them. You prepare it as a draft, then send it now or later.

> [!NOTE]
>
> Before you continue, complete the [Broadcast setup](https://nuntly.com/docs/guides/broadcast-setup.md). You also need [contacts](https://nuntly.com/docs/guides/broadcast-segments.md) and a [template](https://nuntly.com/docs/guides/broadcast-templates.md) with a published version. Broadcasts need an API key with the `broadcast` permission.

## Send your first broadcast

A broadcast takes two requests: one to [create it](https://nuntly.com/docs/api-reference/broadcasts/create-broadcast.md) as a draft, one to [send it](https://nuntly.com/docs/api-reference/broadcasts/send-broadcast.md).

```typescript theme={null}
import { Nuntly } from '@nuntly/sdk';

const nuntly = new Nuntly({ apiKey: process.env.NUNTLY_API_KEY });

// 1. Prepare the broadcast as a draft
const broadcast = await nuntly.broadcasts.create({
  from: 'Acme <updates@news.example.com>',
  name: 'October product update',
  templateId: 'tpl_01k8...',
  segmentId: 'seg_01k8...',
  variables: { month: 'October' },
});

// 2. Send it now. Pass { scheduledAt } to send it later.
await nuntly.broadcasts.send(broadcast.id);
```

The send request answers right away. Delivery then runs in the background, and you follow it through the [status](#status-lifecycle) of the broadcast.

## Prepare a broadcast

A broadcast brings together:

* **A sender.** The `from` address must belong to one of your verified domains.
* **Content.** A [template](https://nuntly.com/docs/guides/broadcast-templates.md#what-a-broadcast-sends). You can replace the subject of the template for this broadcast, and set a reply-to address.
* **An audience.** All your contacts, or one segment. Add a topic to leave out the contacts who unsubscribed from it. See [How the recipients of a broadcast are chosen](https://nuntly.com/docs/guides/broadcast-segments.md#how-the-recipients-of-a-broadcast-are-chosen).
* **Variable values.** The values of the variables your template declares, such as the month of a monthly update. See [Personalization variables](#personalization-variables).
* **A name.** An optional label for your team. Recipients never see it.

You can [change](https://nuntly.com/docs/api-reference/broadcasts/update-broadcast.md) any of these until the broadcast is sent. A scheduled broadcast can still be changed until its date.

### Personalization variables

When the template [declares variables](https://nuntly.com/docs/guides/broadcast-templates.md#declared-variables), the broadcast holds their values. A variable without a value uses the default of the template. A variable with neither a value nor a default prevents sending.

Each value must match the type the template declares. When you change the template of a broadcast, its values must fit the new template too.

## Send now or later

Sending a draft starts it right away. To send later, give a date between 5 minutes and 30 days ahead. Until that date, you can edit a scheduled broadcast, or return it to `draft` to cancel the schedule.

The audience is fixed when sending starts. For a scheduled broadcast, that is when the date arrives, not when you schedule it.

Sending is refused when the broadcast is not ready: no template, a template with no published version, content that breaks a [publication rule](https://nuntly.com/docs/guides/broadcast-templates.md#publish-a-version), or a variable with no value.

Pass an `Idempotency-Key` header to create or send safely on retry. See [Idempotency keys](https://nuntly.com/docs/guides/idempotency.md).

## Status lifecycle

| Status | Meaning | What you can do |
| - | - | - |
| `draft` | Being prepared. Nothing is sent. | Edit, send, schedule, or delete it. |
| `scheduled` | Waiting for its date. | Edit it, return it to `draft`, or delete it. |
| `queued` | Accepted, with its audience fixed. Delivery has not started. | Wait. |
| `sending` | Messages are going out. | Wait. |
| `sent` | Every recipient has been handed over for delivery. This is the final status. | Read the recipients and events. |
| `paused` | Delivery stopped. | Read [the reason](#why-a-broadcast-fails-or-pauses), then contact [support](mailto:support@nuntly.com). |
| `failed` | The broadcast could not be sent, or stopped before the end. | Return it to `draft` when nothing was sent, or delete it. |

You can [delete](https://nuntly.com/docs/api-reference/broadcasts/delete-broadcast.md) a broadcast that is `draft`, `scheduled`, or `failed`. The records of messages it already sent stay.

## Why a broadcast fails or pauses

A failed or paused broadcast shows the reason in the dashboard and in the API. The common causes:

* **The sending domain is not ready.** Fix the domain. See [Domain requirements](https://nuntly.com/docs/guides/broadcast-setup.md#domain-requirements).
* **Too many bounces or complaints**, on this broadcast or across your recent broadcasts. Review your list, then contact [support](mailto:support@nuntly.com).
* **The sending limit of your plan is reached.** Broadcast and transactional email share it. Wait for the next period or upgrade your plan.
* **Sending is paused on our side.** Contact support if it lasts.

## Recipients

The [recipient list](https://nuntly.com/docs/api-reference/broadcasts/list-broadcast-recipients.md) shows who received the broadcast and what happened to each message, using the same statuses as any email. It keeps changing as delivery progresses.

Contacts left out of the broadcast, such as those who unsubscribed, never appear. Recipients follow your [data retention](https://nuntly.com/docs/guides/data-retention.md) window and leave the list once their record expires.

## Events

Each message of a broadcast produces the same email events as any other email: delivered, bounced, complained, and the rest. These events carry a `broadcastId` field, so a [webhook](https://nuntly.com/docs/guides/webhooks.md) you already use for transactional email receives them too. See [Sending events](https://nuntly.com/docs/guides/sending-webhooks.md).

To follow the broadcast as a whole, [retrieve it](https://nuntly.com/docs/api-reference/broadcasts/retrieve-broadcast.md) and read its status.

## Delivery and plan usage

A broadcast is delivered over time, not all at once, so a large one stays in `sending` for a while. Broadcast messages count toward the email volume of your plan.

## Next steps

> [card] [Unsubscribe and suppression](https://nuntly.com/docs/guides/broadcast-unsubscribe.md)
>
> What happens when a recipient unsubscribes

> [card] [Webhooks](https://nuntly.com/docs/guides/webhooks.md)
>
> Receive email events for your broadcast recipients


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.