Broadcasts

A broadcast is one email sent to every eligible contact of an audience or a segment: contacts who are subscribed, reached by its topic and not on the suppression list. Each contact gets their own email, filled in with their values, with an unsubscribe link and your postal address. Broadcasts always go out as marketing email.

Writing one

The subject, HTML and text can use {{{contact.<key>|fallback}}} for the contact's email, first_name, last_name and custom properties. Values are HTML-escaped in the HTML; a contact without a value gets the fallback (or the property's own fallback). {{{unsubscribe_url}}}, {{{preferences_url}}} and {{{mailing_address}}} place the footer's parts yourself; without them coss.com adds a footer.

const { data: broadcast } = await coss.email.broadcasts.create({
  name: "October newsletter",
  segment_id: "seg_01k7c8m4q2f3e9v6t5r1n0p8yz",
  topic: "newsletter",
  from: "Acme <news@acme.com>",
  subject: "What's new, {{{contact.first_name|there}}}",
  preview_text: "Three things we shipped this month",
  html: `<p>Hi {{{contact.first_name|there}}},</p>
<p>…</p>
<p><a href="{{{unsubscribe_url}}}">Unsubscribe</a> · {{{mailing_address}}}</p>`,
  tracking: { opens: true, clicks: true },
});

It starts as a draft, which you can change, preview in the dashboard and send to yourself:

// Up to 5 addresses, filled in as one of your contacts (or with the fallbacks).
await coss.email.broadcasts.test(id, { to: ["me@acme.com"], contact: "ada@example.com" });

Sending

Send it now, or schedule it up to 30 days ahead (pass send or scheduled_at to create to skip the draft). Its content and its recipients are fixed when it starts: contacts added afterwards don't get it, and contacts who unsubscribe before it reaches them are skipped.

await coss.email.broadcasts.send(id, { scheduled_at: "2026-10-20T09:00:00Z" });

// Later: pause it, resume it where it stopped, or cancel it for good.
await coss.email.broadcasts.pause(id);
await coss.email.broadcasts.resume(id);
await coss.email.broadcasts.cancel(id);

A broadcast needs your postal address in the marketing settings and, in production environments, a From address on a verified domain. In production environments its content is screened once before it starts.

Broadcasts are sent at your plan's marketing rate (recipients per second; see the plans in Billing), or slower with rate_per_second, and count toward the daily recipient limit like other email. Pausing or canceling drops the emails not yet handed to the mail provider (the ones already on their way still arrive). coss.com pauses a broadcast itself when sending can't go on:

While a hold lasts, emails not yet handed to the mail provider are dropped too, and made again once it resumes. A broadcast's emails are kept until it is finished, even past the usual retention, so resuming never sends anyone a second one.

Statuses and stats

draft → scheduled → sending (⇄ paused) → sent, or canceled, or failed (see error, e.g. content_rejected). Every broadcast carries its counters, per email:

const { data } = await coss.email.broadcasts.get(id);
const openRate = data && data.stats.delivered > 0 ? data.stats.opened / data.stats.delivered : 0;

// Its emails, one per contact (each is an ordinary email with a `broadcast_id`).
const { data: emails } = await coss.email.broadcasts.listEmails(id);

The broadcast.sending, broadcast.sent, broadcast.paused, broadcast.canceled and broadcast.failed webhooks carry the same stats. A broadcast's emails are kept like any other email (see data retention); its stats are kept with it.