Home / Docs / API Reference / Broadcasts The Broadcasts API lets you create and schedule marketing broadcasts programmatically — perfect for automating a weekly newsletter from your own pipeline. You send us tested, raw
All endpoints authenticate with your API key as a Bearer token, exactly like the Emails API. Your workspace is derived from the key — no workspace ID in the URL.
POST/v1/broadcasts Creates a draft broadcast from raw HTML. The HTML is stored exactly as you send it; tracking links and required footers are applied when the broadcast is scheduled. Response (201): the draft broadcast
• Unsubscribe link is mandatory. If your HTML references {{unsubscribeUrl}} we leave your design untouched. If it doesn't, we append a standard unsubscribe footer — every marketing email must let recipients opt out. One-
Use {{variableName}} anywhere in the HTML, subject or preview text. Variables resolve per recipient from their contact properties — built-ins like {{firstName}}, {{lastName}} and {{email}}, any custom property by its API
POST/v1/broadcasts/:broadcastId/test Sends the broadcast to up to 10 workspace members with a TEST subject prefix. Merge variables are rendered so the email looks exactly like the real send. Always test before scheduling
POST/v1/broadcasts/:broadcastId/schedule Locks the content, resolves the audience and queues the send. Omit sendAt to send immediately, or pass an ISO timestamp up to 90 days out. deliveryMethod controls pacing: ASAP, PR
GET/v1/broadcasts Lists broadcasts (cursor-paginated, filter with ?status=DRAFT). Fetch one with GET /v1/broadcasts/:broadcastId — poll status to follow the lifecycle: DRAFT → SCHEDULED → IN_PROGRESS → COMPLETED.
• (403) — your workspace isn't in the early-access program yet. • (402) — enable the Email API add-on in billing settings. • (403) — your workspace must be verified before sending. • (400) — fix the listed variables or p
