Create and send a broadcast

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.

Before you continue, complete the Broadcast setup. You also need contacts and a template 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 as a draft, one to send it.

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 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. 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.
Variable values. The values of the variables your template declares, such as the month of a monthly update. See Personalization variables.
A name. An optional label for your team. Recipients never see it.

You can change 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, 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, or a variable with no value. Pass an Idempotency-Key header to create or send safely on retry. See Idempotency keys.

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, then contact support.
`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 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.
Too many bounces or complaints, on this broadcast or across your recent broadcasts. Review your list, then contact support.
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 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 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 you already use for transactional email receives them too. See Sending events. To follow the broadcast as a whole, retrieve it 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.

Getting started

AI agents

Sending

Receiving

Broadcast

Configuration

Observability

Webhooks

Best practices

Libraries & tools

Frameworks

Create and send a broadcast

Send your first broadcast

Prepare a broadcast

Personalization variables

Send now or later

Status lifecycle

Why a broadcast fails or pauses

Recipients

Events

Delivery and plan usage

Next steps

Unsubscribe and suppression

Webhooks

​Send your first broadcast

​Prepare a broadcast

​Personalization variables

​Send now or later

​Status lifecycle

​Why a broadcast fails or pauses

​Recipients

​Events

​Delivery and plan usage

​Next steps

Unsubscribe and suppression

Webhooks

Send your first broadcast

Prepare a broadcast

Personalization variables

Send now or later

Status lifecycle

Why a broadcast fails or pauses

Recipients

Events

Delivery and plan usage

Next steps