> ## 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 immediately or schedule it, and follow it through its status lifecycle. Learn what each status means, why a broadcast fails or pauses, and how to list its recipients. A broadcast sends the content of a template to a set of contacts. You create it as a draft, edit it while it is a draft, then send it immediately or schedule it. Before you continue, complete the [Broadcast setup](/docs/guides/broadcast-setup). You also need [contacts](/docs/guides/broadcast-segments) and a [template](/docs/guides/broadcast-templates) with an active version. Broadcasts need an API key with the `broadcast` permission. ## Create a broadcast You create a broadcast in the `draft` status. | Field | Required | Description | | - | - | - | | `from` | Yes | The sender email address. Its domain must be one of your verified sending domains with sending enabled. Nuntly derives the sending domain from this address. | | `name` | No | A plain internal label, 1 to 255 characters, shown only to your team. Purely for your own reference: it has no effect on delivery, targeting, or rendering, and there's no uniqueness check. | | `templateId` | No | The template to send. See [What a broadcast sends](/docs/guides/broadcast-templates#what-a-broadcast-sends). | | `subject` | No | A subject, up to 200 characters. When you omit it, the subject of the bound template version is used. | | `replyTo` | No | One address, or a list of addresses, for replies. | | `segmentId` | No | Send to the members of this segment instead of all contacts. | | `topicId` | No | Skip the contacts that unsubscribed from this topic. | | `variables` | No | Values for the variables declared by the bound template version, keyed by name. See [Personalization variables](#personalization-variables). | How `segmentId` and `topicId` combine into the recipients is described in [How the recipients of a broadcast are chosen](/docs/guides/broadcast-segments#how-the-recipients-of-a-broadcast-are-chosen). While the broadcast is a `draft` or `scheduled`, you can edit `from`, `name`, `templateId`, `subject`, `replyTo`, `topicId`, `segmentId`, and `variables`. Setting `name`, `templateId`, `subject`, `replyTo`, `topicId`, or `segmentId` to `null` clears it. Omitting `variables` leaves the stored values unchanged; sending `{}` clears them. A single edit request either changes those fields or returns the broadcast to `draft`, never both. `name` is frozen once the broadcast reaches `queued`, the same as `templateId`, `topicId`, and `segmentId`. The create and send requests support the `Idempotency-Key` header. See [Idempotency keys](/docs/guides/idempotency). ### Personalization variables When the bound template version [declares variables](/docs/guides/broadcast-templates#declared-variables), supply their values as an object keyed by the declared name, in `variables` on create or edit. * A variable with no supplied value falls back to the version's own default. A required variable, one with no default, that still has no value when the broadcast is sent blocks sending, refused with `broadcast_variable_missing`. * A value must name a declared variable and match its declared type, or the write is refused: `broadcast_variable_unknown`, `broadcast_variable_type_mismatch`, or `broadcast_variable_value_too_large` for a string value over 1 KB serialized. * Supplying any value on a broadcast with no bound template, or whose template has no active version, is refused as `broadcast_variable_unknown`, since there's nothing to declare against it. * Re-pointing a broadcast to a different template or version is refused with `broadcast_variables_do_not_fit_version` when the stored values no longer fit the newly bound version's declarations. * Detaching the template (`templateId: null`) while values are stored is refused with `broadcast_variables_must_be_cleared`, unless the same request also clears `variables`. ## Send a broadcast Send a `draft` broadcast to accept it into delivery. Without a body, the broadcast is sent immediately and its status becomes `queued`. With a `scheduledAt` date, its status becomes `scheduled`. The request returns a `202` response with the broadcast id and its new status before any recipient is mailed. Delivery continues in the background. Nuntly refuses the request in these cases: | Response | Cause | | - | - | | `409` | The broadcast is not a `draft`. | | `422` | The broadcast has no template bound, the template has no active version, or the content breaks a [publication rule](/docs/guides/broadcast-templates#publish-a-version). | | `422` | A declared variable with no default has no supplied value (`broadcast_variable_missing`). See [Personalization variables](#personalization-variables). | | `422` | The `scheduledAt` date is less than 5 minutes or more than 30 days ahead. | | `500` | The stored content could not be read right now. Try again shortly. | ### Schedule a broadcast A scheduled broadcast is sent automatically at `scheduledAt`. Until then you can edit it, return it to `draft`, or delete it. * The contacts that can receive the broadcast are fixed when the schedule fires, not when you schedule it. * The content is checked again when the schedule fires. When the content no longer passes the check, the broadcast is not sent and stays `scheduled`, and no further attempt is made. Return it to `draft`, fix the content, and schedule it again. * Returning a scheduled broadcast to `draft` cancels the schedule. ## Status lifecycle | Status | Meaning | What you can do | | - | - | - | | `draft` | Being prepared. Nothing is sent. | Edit, send, schedule, or delete it. | | `scheduled` | Waiting for `scheduledAt`. | Edit it, return it to `draft`, or delete it. | | `queued` | Accepted, with the sending contacts fixed. Delivery has not started. | Wait. | | `sending` | Delivery has started. Nuntly processes the contacts in pages. | Wait. | | `sent` | Nuntly went through the whole recipient set and queued the last page for delivery. This is the final status. | Read the recipients and events. | | `paused` | Delivery stopped, with a reason in `statusReason`. | Read the reason. See below. | | `failed` | Nuntly refused or abandoned the broadcast, with a reason in `statusReason`. | Return it to `draft` when nothing was sent, or delete it. | `sent` means that the last page of contacts was queued. Messages can still be waiting to be sent, and it does not mean that every message was delivered. Follow the outcome of each recipient in the [recipient list](#recipients) or through [events](#events). A broadcast with no contacts to mail goes through `sending` to `sent` without sending anything. You control these transitions: * `draft` to `queued` or `scheduled`, by sending it. * `scheduled` to `draft`, by returning it to `draft`. * `failed` to `draft`, when the broadcast has not sent to any recipient. Nuntly controls every other transition. Once a broadcast is `queued`, you cannot cancel it. There is no API action to stop a running broadcast or to resume a paused one. If a broadcast is paused, contact [support](mailto:support@nuntly.com). A `failed` broadcast that already sent to at least one recipient cannot return to `draft`. You can only delete it. ### Delete a broadcast You can delete a broadcast that is `draft` or `scheduled`, or `failed` after it sent to at least one recipient. A `failed` broadcast that sent to nobody must return to `draft` first. Deleting a broadcast does not remove the send records of the recipients it already mailed. ## Why a broadcast fails or pauses A broadcast in the `failed` or `paused` status carries `statusReason`, an object with a `reason` code and usually a `detail` sentence. Nuntly checks eligibility after your send request is accepted, so a refusal appears as a status and never as an error on the send request. See [Domain requirements](/docs/guides/broadcast-setup#domain-requirements). | Reason | Status | Meaning | | - | - | - | | `organization_not_enabled` | `failed`, or `paused` once it has sent to a recipient | Your organization is not enabled to send. | | `domain_not_verified` | `failed` | The sending domain is not verified. | | `domain_sending_not_enabled` | `failed`, or `paused` once it has sent to a recipient | Sending is not enabled on the sending domain. | | `domain_authentication_incomplete` | `failed` | DKIM or DMARC is not verified on the sending domain. The detail names the missing record. | | `domain_absent` | `failed` | The sending domain no longer exists. | | `broadcast_provisioning_timeout` | `failed` | The broadcast sending identity of the domain was not ready in time. | | `orchestration_abandoned` | `failed` | Delivery could not be resumed and was stopped. | | `broadcast_reputation_stopped` | `paused` | Broadcast sending is stopped on the domain after a reputation problem. | | `broadcast_pause_level1` | `paused` | The bounce or complaint rate of this broadcast crossed its threshold. | | `org_bounce_rate_short`, `org_complaint_rate_short`, `org_bounce_rate_7d`, `org_complaint_rate_7d`, `org_bounce_rate_30d`, `org_complaint_rate_30d` | `paused` | The bounce or complaint rate of your organization's broadcasts crossed its threshold over that window. | | `account_alarm`, `account_pressure_signal` | `paused` | Broadcast sending is paused on the sending account of the domain. | | `operator_global_pause` | `paused` | Broadcast sending is paused platform-wide by an operator. | | `combined_ceiling_exhausted` | `paused` | The daily or monthly cap of your plan is reached. Broadcast and transactional sends count toward the same cap. | | `content_unavailable` | `paused` | The stored content of the bound version could not be found. | A `failed` broadcast that has not sent to anyone can return to `draft` and be sent again once you fix the cause. ## Recipients Retrieve the recipients of a broadcast to see who was mailed and what happened to each recipient. Each entry has an `id`, the `contactId`, the `email` address, an `outcome`, and `createdAt`. * `outcome` is the current status of the send record of the recipient, using the same statuses as an email. It keeps changing as delivery progresses. * `contactId` is `null` once the contact has been deleted. * Contacts that were removed from the recipient set never appear, because they received no message and have no send record. This includes contacts that unsubscribed or that are on the suppression list. * Send records follow your [data retention](/docs/guides/data-retention) window. A recipient whose send record expired stops being listed. The list of a broadcast whose records all expired is empty. ## Events Nuntly does not emit broadcast-level events. Read the status of the broadcast to follow its progress. The broadcast object has no recipient counts. Each message sent to a recipient produces the same email events as any other email, such as delivery, bounce, and complaint events. For a broadcast recipient these events carry a `broadcastId` field with the id of the broadcast. Subscribe to them with [webhooks](/docs/guides/webhooks). See [Sending events](/docs/guides/sending-webhooks) for the event types. ## Delivery pace and plan usage Nuntly currently processes a broadcast in pages of 50 contacts, about 10 seconds apart. A large broadcast therefore stays in `sending` for a while. Broadcast sends count toward your plan usage. See `combined_ceiling_exhausted` above for what happens when a cap is reached. ## Operations | Operation | Request | | - | - | | Create a broadcast | `POST /broadcasts` | | List broadcasts | `GET /broadcasts` | | Retrieve a broadcast | `GET /broadcasts/{broadcastId}` | | Edit a broadcast, or return it to `draft` | `PATCH /broadcasts/{broadcastId}` | | Send or schedule a broadcast | `POST /broadcasts/{broadcastId}/send` | | List the recipients of a broadcast | `GET /broadcasts/{broadcastId}/recipients` | | Delete a broadcast | `DELETE /broadcasts/{broadcastId}` | ## Next steps What happens when a recipient unsubscribes Receive email events for your broadcast recipients This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.