Create and send a broadcast

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.

​

Create a broadcast

You create a broadcast in the draft status. How segmentId and topicId combine into the recipients is described in 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.

​

Personalization variables

When the bound template version declares 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:

​

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

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 or through 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. 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. 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 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. See Sending events 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

​

Next steps