Introducing Broadcast, a broadcast email API for developers

Your password resets already go through Nuntly. The product update you send to your users once a month probably goes through a second tool, with a second list, a second DNS setup, and a second set of webhooks.

Today we're opening Broadcast to every Nuntly account. Broadcast is a broadcast email API: you store contacts in Nuntly, choose who receives a send with segments and topics, write the content once as a versioned template, and send or schedule it. Same API key, same verified domains, same webhooks.

You can run it from the API or from the dashboard, and every message follows the unsubscribe and authentication rules that mailbox providers now enforce on bulk senders. The Broadcast overview has the full model. This post walks through what's in it.

What a broadcast email API covers

A broadcast email API sends one message to many contacts you store, and handles segmentation, opt-outs, and unsubscribes for you. Five objects make it work.

A broadcast skips every contact who unsubscribed, from its topic or from your broadcasts, and every address on your suppression list. The recipient rules cover the details.

Send your first broadcast with the API

The script below uses the TypeScript SDK to go from an empty account to a scheduled broadcast. It reads your key from NUNTLY_API_KEY.

import { Nuntly } from '@nuntly/sdk';

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

// 1. A contact in a segment
const contact = await nuntly.contacts.create({ email: 'jane@yourcustomer.com' });
const segment = await nuntly.segments.create({ name: 'Beta testers' });
await nuntly.contacts.segments.add(contact.id, segment.id);

// 2. A template with one published version
const template = await nuntly.templates.create({ name: 'Monthly product update' });
const version = await nuntly.templates.versions.create(template.id, {
  subject: 'What shipped in {{month}}',
  html: '<p>Here is what shipped in {{month}}.</p><p><a href="{{system.unsubscribeUrl}}">Unsubscribe</a></p>',
  variables: [{ name: 'month', type: 'string' }],
});
await nuntly.templates.versions.publish(template.id, version.id);

// 3. A broadcast to the segment, scheduled
const broadcast = await nuntly.broadcasts.create({
  from: 'Your App <updates@news.yourapp.com>',
  templateId: template.id,
  segmentId: segment.id,
  variables: { month: 'October' },
});

const { status } = await nuntly.broadcasts.send(broadcast.id, {
  scheduledAt: '2026-11-03T09:00:00.000Z',
});

The broadcast is now scheduled. Leave out scheduledAt to send it right away instead. You can schedule a broadcast from 5 minutes to 30 days ahead.

Two details in that script carry weight:

• {{month}} is a declared variable. Its value belongs to the broadcast, so the same template serves every monthly send. Per-recipient values use contact properties instead, written {{contact.PropertyName}}.
• {{system.unsubscribeUrl}} is mandatory. Publishing a version whose HTML lacks it fails.

The create and send calls accept an idempotencyKey request option, the same way transactional sends do. Pass one on create, and a retried request returns the original response instead of creating a second broadcast.

One-click unsubscribe and bulk sender rules

Gmail requires senders of more than 5,000 messages a day to Gmail accounts to authenticate with SPF, DKIM, and DMARC, and to support one-click unsubscribe. Google's email sender guidelines put it directly:

"Marketing messages and subscribed messages must support one-click unsubscribe."

Broadcast adds the unsubscribe mechanics to every message and checks authentication before it sends.

One-click unsubscribe: defined by RFC 8058, it adds a List-Unsubscribe-Post: List-Unsubscribe=One-Click header next to the List-Unsubscribe header, so a mail client can unsubscribe the recipient with a single POST request.

Every broadcast message carries both headers, plus the visible link your template places with {{system.unsubscribeUrl}}.

Opening the link never unsubscribes anyone. Link scanners and mail previews open links on their own, so the page asks the recipient to confirm. A one-click POST from a mail client unsubscribes immediately.

An unsubscribe applies to every later broadcast from your organization. Transactional email keeps flowing: a user who leaves your product updates still gets their password reset.

On the authentication side, Broadcast has the same domain requirements as transactional sending: DKIM, SPF, and MX verified on the sending domain. DMARC stays optional, but Gmail and Yahoo expect it from bulk senders, so add a record before a large send. The domain is checked before sending starts and again while it runs, so a domain that loses its records mid-send stops that broadcast. The setup guide lists each check.

Broadcast and transactional email: one domain or two

You can send broadcasts from the domain you already verified for transactional email, with no extra DNS records. We recommend a second domain, such as a news. subdomain next to a mail. one, so each kind of sending builds its own reputation with mailbox providers. The setup guide explains the choice.

Both share one suppression list. An address that bounced permanently or filed a complaint is skipped by both.

Run a broadcast from the dashboard

Everything above also works from the dashboard, in the Broadcast section of the sidebar.

A typical flow from the dashboard:

1. Add contacts and set their properties under Contacts. Set a contact's topic subscriptions from the same page.
2. Create segments and add members under Segments.
3. Open Templates to browse a template's versions, preview their content, and publish one.
4. Create a broadcast: sender address, an internal name, subject, reply-to, template, topic, segment, and the template's variables.
5. Click Send now or Schedule. The confirmation dialog names the audience it will reach before you confirm.
6. Follow the status, then the recipient list with the outcome of each send.

You write template versions with nuntly.templates.versions.create() and publish them from the API or the dashboard.

Follow delivery with webhooks

Each message produces the same email events as any transactional email: delivered, bounced, complained, and the rest. For a broadcast recipient, these events carry a broadcastId field. If you already consume webhooks, your handler sees broadcast traffic with no new event type to wire up.

Get started

1. Check that your sending domain is verified, and add a DMARC record if it has none.
2. Create an API key with Full access. A Sending only key cannot use Broadcast.
3. Follow Create and send a broadcast, or open the Broadcast section of the dashboard.

Frequently asked questions

Do I need a separate domain for broadcasts?

No, the domain you already verified works. We recommend one, though: a separate domain, such as a subdomain, gives broadcasts and transactional email their own reputation with mailbox providers. Adding a DMARC record before a large send is recommended too.

Does an unsubscribe stop my transactional emails?

No. An unsubscribe only removes the address from later broadcasts. A permanent bounce or a complaint is different: it adds the address to the suppression list, which applies to both.

Where do I write template content?

You create template versions through the API, then publish them from the API or the dashboard. Versions are immutable, so a change always means a new version.

Can I cancel a broadcast?

Yes, while it is still scheduled. Once you send it, or once its scheduled time comes, it can no longer be canceled.

Do broadcasts count toward my plan?

Yes. Broadcast and transactional sends count toward the same plan volume.