Documentation

Broadcasts

Drafting, scheduling, tracking, A/B tests and automatic winner sends.

A broadcast is an audience campaign over the marketing stream. Create a draft — the dashboard includes a rich text editor with headings, lists, links and an HTML source view, plus a block builder with heading, paragraph, button, image, divider, spacer and two-column blocks with alignment, colour and width controls, per-block margins, a global theme and image uploads — then send immediately or schedule it. Save a block set as a reusable preset and insert it into another campaign. Drafts and templates store the block JSON alongside the generated HTML, so they reopen as editable blocks. Starting a broadcast snapshots the audience into a fixed recipient list, excluding unsubscribed contacts. The worker creates one marketing message per recipient, honours suppression and plan quota, and records each recipient's status independently.

{{variable}} placeholders resolve from the contact's name, email and attributes. A template fills in only where the broadcast's own subject or body is empty. Recipient states are pending, processing, queued, skipped (unsubscribed or suppressed) and failed (validation, domain or quota). Cancelling stops remaining work but does not recall messages already queued. Broadcast messages carry source=broadcast, a broadcast_id tag and a broadcast_variant tag.

create a tracked A/B broadcast with automatic winner selection
POST /v1/broadcasts
{
  "name": "November product update",
  "audience_id": "aud_…",
  "from": "[email protected]",
  "from_name": "Acme",
  "subject": "What's new in November",
  "html": "<p>Hi {{name}},</p>",
  "text": "Hi {{name}},",
  "track_opens": true,
  "track_clicks": true,
  "variant_b_subject": "A shorter subject",
  "variant_b_html": "<p>Hi {{name}}, quick update…</p>",
  "variant_split_percent": 50,
  "winner_enabled": true,
  "winner_metric": "open",
  "winner_wait_minutes": 240,
  "winner_test_percent": 20
}

GET  /v1/broadcasts/brd_…           # detail, recipients and analytics
POST /v1/broadcasts/brd_…/send       # send now, or {"scheduled_at":"…"}
POST /v1/broadcasts/brd_…/test       # {"to":"[email protected]","variant":"b"}
POST /v1/broadcasts/brd_…/cancel

Open and click tracking. Set track_opens or track_clicks to rewrite the HTML per recipient with signed tokens. GET /t/o/{token} records an open and returns a 1×1 GIF; GET /t/c/{token}?u=… records a click and redirects to the signed target. Tokens cannot be retargeted, and mailto:, tel: and fragment links are left alone. Analytics report opens, unique opens, clicks and unique clicks.

A/B tests. Variant B can override the subject, HTML and text independently; empty B fields fall back to A. Without a winner test, the configured split is fixed at snapshot time and both variants send together. For an automatic winner send, A and B each receive half of the winner_test_percent sample and the remaining recipients wait. After winner_wait_minutes, the higher unique open or click rate among delivered test recipients wins (ties go to A), the remainder receives that variant, and broadcast.winner_selected is emitted. Analytics expose both final and test-sample results per variant. A third variant C can be added as a multivariate split; B + C must total less than 100 and automatic winner selection remains A/B only.

Broadcasts can target a saved segment instead of an audience and can set a topic. The recipient snapshot applies segment filters, global unsubscribe state and topic opt-outs. Each campaign message carries a signed List-Unsubscribe header and a preference footer.

Need the full API surface? OpenAPI 3.1.