Broadcasts

const draft = {  audienceIds: ['aud_4c1b8e2a7d9f05c36b4e8a71'],  from: 'Acme <[email protected]>',  subject: '{{firstName|Hello}}, the September release is out',  html: '<p>Hi {{firstName|there}},</p><p>Here is what changed this month.</p>',  text: 'Hi {{firstName|there}}, here is what changed this month. Unsubscribe: {{unsubscribeUrl}}',  tags: { campaign: 'release-2026-09' },} const reach = await nextmail.broadcasts.preview(draft)console.log(reach.recipients, reach.unsubscribed, reach.suppressed) const broadcast = await nextmail.broadcasts.send(draft) let latest = await nextmail.broadcasts.get(broadcast.id)while (['scheduled', 'queued', 'sending'].includes(latest.status)) {  await new Promise((resolve) => setTimeout(resolve, 5_000))  latest = await nextmail.broadcasts.get(broadcast.id)} for await (const copy of nextmail.broadcasts.iterateRecipients(broadcast.id)) {  console.log(copy.email, copy.status, copy.opens, copy.clicks)} const bounced = await nextmail.broadcasts.listRecipients(broadcast.id, { filter: 'bounced' })if (bounced.items[0]) {  const copy = await nextmail.broadcasts.getRecipient(broadcast.id, bounced.items[0].emailId)  console.log(copy.subject, copy.bouncedAt)} const stats = await nextmail.broadcasts.stats(broadcast.id, { grain: 'day' })console.log(stats.totals.opened, stats.totals.clicked, stats.totals.unsubscribed) const lately = await nextmail.broadcasts.stats(broadcast.id, { days: 1 })console.log(lately.window?.opened) const month = await nextmail.broadcasts.analytics({ days: 30 })for (const row of month.broadcasts) console.log(row.subject, row.sent, row.opened) const later = await nextmail.broadcasts.send({ ...draft, scheduledAt: 'P1D' })await nextmail.broadcasts.cancel(later.id) const history = await nextmail.broadcasts.list({ audienceId: draft.audienceIds[0] })console.log(latest.status, latest.counts.sent, history.items.length)

A broadcast sends one message to everybody in one or more audiences, as a separate copy for each person. Every copy has exactly one recipient and no cc or bcc, so nobody sees who else it went to, and every copy is an ordinary email with its own msg_ id, events, tracking and webhooks. listRecipients lists them with what happened to each. The copies are not filed in the Sent folder, because the broadcast is the record.

send resolves straight away with the broadcast queued, or scheduled when you pass scheduledAt, and the sending runs in the background. send needs emails:send and audiences:read, preview needs audiences:read, list, listAll, iterate, get, listRecipients, listAllRecipients, iterateRecipients, getRecipient, stats and analytics need emails:read, and cancel needs emails:send.

subject, html and text are filled in for each person from their contact. {{firstName}} is the first word of the contact name, {{lastName}} the rest of it, {{name}} the whole name, {{email}} the address the copy goes to and {{unsubscribeUrl}} the link that unsubscribes them.

A custom field of the contact is {{attributes.<key>}}, such as {{attributes.plan}} for the field plan.

Every field takes a fallback after a bar, used when the contact has no value for it, so {{firstName|there}} becomes "there" for a contact saved without a name. Values are escaped in html, and any other {{…}} is left exactly as written.

Pass template instead of html and text to send a stored template. The same five values reach it as props, but only the props the template declares, so a template that declares firstName gets it and one that does not is never refused for it. Anything in template.props goes to every copy alike.

Pass abTest to send, createDraft or update to try 2 to 4 versions on a share of the people first, each in variants with its own subject, or its own html and text. Once waitMinutes have passed, the version with the highest share of opens, or of clicks when metric is clicks, goes to everybody else. stats shows how each version did and which one won.

Every copy carries the one-click unsubscribe headers that let a mail client show its own unsubscribe button, which the large mailbox providers require of bulk mail. A body or a template that does not place {{unsubscribeUrl}} itself gets a short footer with the link, in English, which also names the sender and shows the postal address once marketingPostalAddress is set with settings.update. A template receives unsubscribeUrl whether it declares it or not.

Unsubscribing takes the person off all of the marketing mail of the workspace. AudienceContactResource.unsubscribedAt shows it in every audience they are in, suppressions.listUnsubscribes lists them, and taking them out of an audience and adding them again, or deleting the contact and making it again, leaves them unsubscribed. They stay in the address book, and mail sent to them one message at a time still goes. Only they can subscribe again, from the unsubscribe page or a sign-up form they confirm from their inbox.

A broadcast reaches every contact in at least one of audienceIds, once however many of them hold it. It skips a contact that has unsubscribed, and an address on the suppression list after a bounce or a complaint, or because somebody added it there. A contact added to one of the audiences after send but before the sending reaches it is included. All contacts, the built-in audience of everyone the workspace has written to, is refused with 422 audience_is_everyone.

preview returns the same numbers without sending: recipients, unsubscribed and suppressed. A send that would reach nobody throws 422 no_recipients.

get reads counts live from the copies, so poll it while a broadcast sends. status moves from scheduled or queued to sending and settles on sent once every copy handed over has gone out or failed. It stays sending while copies are still waiting, even after completedAt says the last person was reached. failed means the whole broadcast stopped, and lastError says why: the from address can no longer be sent from, the template stopped resolving, the plan ran out part way, the sending itself kept failing, or not one copy could be written.

cancel stops a broadcast that is scheduled, queued or sending. Nobody else is added and every copy still waiting is cancelled, while copies that have gone cannot be recalled. Once every copy has gone, cancel throws 409 broadcast_not_cancellable, and cancelling a cancelled broadcast resolves with it as it stands.

listRecipients resolves one page of the people a broadcast went to, one row per copy, sorted by address, as { items, hasMore, nextCursor }. listAllRecipients walks every page into one array and iterateRecipients yields one copy at a time, fetching the next page only when the loop asks for it. limit goes from 1 to 200 and defaults to 50, and a cursor goes back with the same filter and q.

BROADCAST_RECIPIENT_FILTERS names each filter, and q searches the address and the name, ignoring case. Opens and clicks leave out image proxies and link scanners, and stay 0 when the broadcast went out with tracking off.

getRecipient(id, emailId) resolves one copy: the same row, plus subject, html and text exactly as that person received them, with the merge fields filled in and their own unsubscribe link. The HTML is from before open and click tracking was added. An emailId that is not a copy of this broadcast throws 404 recipient_not_found, and an unknown broadcast throws 404 broadcast_not_found.

stats resolves the totals and a series. totals counts copies sent, delivered, bounced, complained and failed, with pending for the ones still waiting, and people who opened, clicked and unsubscribed, with opens and clicks as event counts. series is sparse and oldest first, one bucket per grain (minute, hour or day, defaulting to hour) in which something happened, cut in offsetMinutes east of UTC. It counts each person once, at the first time it happened to them, so it adds up to the totals.

send, get and cancel each resolve to one of these. list resolves to a page of them, { items, hasMore, nextCursor }, newest first, and listAll and iterate walk every page. preview resolves to a BroadcastPreviewResource with audienceIds, recipients, unsubscribed and suppressed. listRecipients resolves to a page of BroadcastRecipientResource rows, getRecipient to a BroadcastRecipientContentResource and stats to a BroadcastStatsResource.

Each row of listRecipients, listAllRecipients and iterateRecipients. BroadcastRecipientContentResource, from getRecipient, adds subject, html and text.