Retrieve a broadcast
One broadcast with `counts` read live from its copies, which makes this the call to poll while it sends.
Runs the real call on your workspace.
GET /broadcasts/{id}
One broadcast with counts read live from its copies, which makes this the call to poll while it sends.
Example
Needs emails:read.
curl "$OE/broadcasts/brd_5a8c1e3f7b2d94a06c8e1f3b" -H "$AUTH"{ "object": "broadcast", "id": "brd_5a8c1e3f7b2d94a06c8e1f3b", "status": "sending", "mode": "live", "source": "api", "audienceIds": ["aud_4c1b8e2a7d9f05c36b4e8a71"], "from": "Acme <[email protected]>", "subject": "{{firstName|Hello}}, the September release is out", "counts": { "recipients": 412, "created": 250, "skipped": 1, "failedToQueue": 0, "queued": 38, "sending": 2, "sent": 209, "failed": 1, "cancelled": 0 }, "lastError": null, "scheduledAt": null, "startedAt": "2026-09-23T12:00:02.000Z", "completedAt": null, "cancelledAt": null, "createdAt": "2026-09-23T12:00:00.000Z", "updatedAt": "2026-09-23T12:00:41.000Z"}An id from another workspace is a 404 broadcast_not_found, and so is a broadcast sent from an address or domain that a key limited to particular addresses or domains does not hold.
For who each copy went to and what happened to it, list the copies with GET /broadcasts/{id}/recipients and read one with GET /broadcasts/{id}/recipients/{emailId}. GET /broadcasts/{id}/stats adds them up.
Statuses
| Status | Means |
|---|---|
| scheduled | Waiting for scheduledAt. |
| queued | Waiting for the sending to start. |
| sending | Walking the audiences, or finished walking them while copies are still waiting to go. completedAt is set once the last person was reached. |
| sent | Every copy handed over has gone out or failed. |
| cancelled | Stopped by POST /broadcasts/{id}/cancel. |
| failed | The whole broadcast stopped: the from address can no longer be sent from, the template stopped resolving, the plan ran out part way, the sending itself kept failing, or not one copy could be written. lastError says which. |
Counts
| Count | Means |
|---|---|
| recipients | The estimate taken when the broadcast was created. It does not move afterwards. |
| created | Copies written so far, one per person reached. |
| skipped | People passed over because their address was suppressed by the time the sending reached them. |
| failedToQueue | People whose copy could not be written. lastError names the most recent one. |
| queued, sending, sent, failed, cancelled | The copies by the state each one is in now, counted live. |
Webhook events
Four events follow a broadcast: broadcast.sending when it starts going out, broadcast.sent when every copy has been handed over for sending, broadcast.failed when it stops because it cannot go out, and broadcast.cancelled when it is cancelled before it finishes. Each carries broadcastId, status, subject, fromEmail, audienceIds, recipients, created, skipped, failed, error and at.
Every copy still sends its own email.* events as it goes, and GET /broadcasts/{id} reads sending until the last one has gone out. These four are not in the default set, so an endpoint receives them only when it names them in eventTypes, and an endpoint limited to some addresses or domains never does, because a broadcast goes to the audiences of the whole workspace.