Broadcasts

A broadcast is one email (subject, HTML, optional text) sent to every subscribed contact in one audience, with each contact's name and data filled in. Flaresend sends it in the background and adds a one-click unsubscribe link to every copy.

Turn broadcasts onCopy Anchor Link

Broadcasts are disabled per project until you turn them on. Until then, creating or sending a broadcast fails with 403 broadcasts_disabled.

• Dashboard: project Settings, then turn on broadcasts.
• Admin API: PATCH /v1/admin/projects/:slug with { "broadcastsEnabled": true }.

The recipient cap is the mailer's BROADCAST_MAX_RECIPIENTS variable (default 500). It applies to the number of subscribed contacts in the audience when you press send. See Configuration.

Also set the TRACKING_SECRET secret on the mailer. Without it, broadcasts go out without unsubscribe links and headers. See Unsubscribe.

LifecycleCopy Anchor Link

Only drafts can be edited. scheduled, sending and draft broadcasts can be canceled. A scheduled or sending broadcast can't be deleted until you cancel it (409 broadcast_active).

Create and sendCopy Anchor Link

const broadcast = await flaresend.broadcasts.create({
  audienceId: 'aud_01K6B4F7R2M9T5Q1V8X3N6P4WD',
  from: 'Acme <hello@acme.com>',
  subject: 'What shipped in September, {{first_name}}',
  html: '<p>Hi {{first_name}},</p><p>Here is what is new…</p><p><a href="{{unsubscribe_url}}">Unsubscribe</a></p>',
  text: 'Hi {{first_name}},\n\nHere is what is new…\n\nUnsubscribe: {{unsubscribe_url}}',
});

await flaresend.broadcasts.send(broadcast.id);
// or
await flaresend.broadcasts.send(broadcast.id, { scheduledAt: '2026-10-01T09:00:00Z' });

const b = await flaresend.broadcasts.get(broadcast.id);
b.status; // 'sending'
b.total;  // subscribed contacts when it started
b.sent;   // emails queued so far
b.counts; // { queued: 12, delivered: 80, bounced: 1 }: the broadcast's emails by status

How sending worksCopy Anchor Link

A cron job runs every 5 minutes. On each run it:

1. Moves broadcasts whose scheduledAt has passed from scheduled to sending.
2. For up to 10 sending broadcasts, takes the next 100 contacts in the audience and sends each one an email.

So a broadcast starts within about 5 minutes of being sent or of its scheduled time, and goes out at up to 100 emails per 5 minutes. A 500-contact broadcast takes about 25 minutes.

For each contact:

• Contacts that are unsubscribed or on the suppression list are skipped.
• The email is a normal send: it appears in your email log, fires webhooks, and counts toward the project's daily limit. It is tagged broadcast_id: <id>, so you can filter the email list with tag=broadcast_id:bc_….
• Each email has the idempotency key bc:<broadcastId>:<contactId>, so a contact never gets the same broadcast twice, even if a run is repeated.
• If the project hits its rate limit or daily limit, the run stops there and the next run carries on from the same contact.
• Any other error for one contact (for example an address that fails validation) is logged and that contact is skipped.

Canceling stops the next runs. Emails already queued before you canceled still go out.

If the project is disabled or broadcasts are turned off while one is sending, the broadcast is canceled on the next run.

PersonalizeCopy Anchor Link

Subject, HTML and text are Mustache-style templates, rendered once per contact with these variables:

first_name, last_name, email and unsubscribe_url win over keys with the same name in data. In HTML, values are HTML-escaped; use {{{triple braces}}} to insert raw HTML. {{#if plan}}…{{else}}…{{/if}} and {{#each list}}…{{/each}} work too.

Edit, cancel, deleteCopy Anchor Link

await flaresend.broadcasts.update(id, { subject: 'New subject' }); // drafts only, else 409 broadcast_not_draft
await flaresend.broadcasts.cancel(id);                             // draft, scheduled or sending
await flaresend.broadcasts.remove(id);                             // not while scheduled or sending

APICopy Anchor Link