Skip to Content
Docs
Guides

Broadcasts

One-off marketing sends to an audience or segment — create, send, cancel, stats.

A broadcast is a one-off marketing send to an audience or segment with its own draft lifecycle — separate from transactional POST /v1/email traffic.

In the console

No code needed — open Broadcasts and click New broadcast.

  1. Name it and click Create draft. The name is internal only; recipients never see it.
  2. Compose — add a subject, choose a verified From domain, and paste the HTML body. Click Save draft as you go.
  3. Pick the target — an audience or a saved segment.
  4. Send — choose Send now or Schedule for later, then click Send broadcast. You can cancel it until it starts sending.

The New broadcast panel in the emitd console, asking for an internal name

The rest of this page covers the same lifecycle over the API.

Lifecycle

draft ──send──▶ scheduled (future scheduled_at)
  │       └───▶ sending   (fan-out cron's next tick)
  │                  └──▶ sent
  └──cancel──▶ cancelled ◀──cancel (only from draft/scheduled)
StepEndpoint
Create a draftPOST /v1/broadcasts
Edit the draftPATCH /v1/broadcasts/{id} — draft only, else 409 not_editable
Send or schedulePOST /v1/broadcasts/{id}/send — draft only, else 409 not_draft
CancelPOST /v1/broadcasts/{id}/cancel — draft/scheduled only, else 409 not_cancelable
Read statsGET /v1/broadcasts/{id}
DeleteDELETE /v1/broadcasts/{id} — hard delete, any status

Sending

POST /v1/broadcasts/{id}/send validates first — subject, body_html or body_text, your postal address in the console's Settings, a target that still resolves, and a verified from_domain_id (errors: invalid_subject, invalid_body, missing_postal_address, invalid_target, domain_not_verified). It then:

  • computes a best-effort total_recipients snapshot,
  • sets status = scheduled if you passed a future scheduled_at (epoch ms), otherwise status = sending.

Nothing is enqueued by the call itself — the per-minute fan-out cron picks up sending broadcasts on its next tick. If your postal address has been removed by then, the cron pauses the broadcast instead of sending it.

POST /v1/broadcasts/{id}/send
{ "scheduled_at": 1783472400000 }

Personalizing

The subject and bodies can use {{email}} and any of the contact's attributes, such as {{name}}. A contact without that attribute gets a blank, so write copy that still reads well: Hi {{name}} becomes Hi for them. Values are HTML-escaped in the HTML body.

{{unsubscribe_url}} and {{year}} are filled in as each email is sent. Automation send steps work the same way.

Every broadcast carries an unsubscribe link and your postal address, in a footer we add. To place the link yourself, use <a href="{{unsubscribe_url}}"> and only the address is added. A link to your own preference page doesn't replace it, so that email has both: contact data ends up in the body, and it can't be allowed to look like an opt-out.

Targeting

target_kind is audience or segment with the matching target_id — built from Contacts & audiences. Re-validating a target happens when a PATCH touches target_kind/target_id.

Listing & pagination

GET /v1/broadcasts pages with ?limit= (max 100) and a composite "{created_at}:{id}" cursor.

Multi-step programs

For wait/branch logic (drip sequences), use /v1/automations: create steps (send / wait / branch), then activate, pause, and enroll contacts. Guardrails are explicit: no_steps, not_activatable, wait_out_of_range, bad_branch_filter, and friends.

On this page