Broadcasts

A broadcast is one message to many contacts, as opposed to a transactional message to one person. Create it, review it, then send it.

The split with the dashboard

The API covers the lifecycle: create, update, send, test, cancel. It deliberately does not cover authoring. The editor, image hosting, previews and the pre-send checklist stay in the dashboard, because they are interface concerns rather than contract ones.

In practice that means the API takes html and text and the dashboard is where a broadcast is composed. Both act on the same broadcast, so you can create one from code and finish it on screen, or the reverse.

Create

curl https://api.epostix.com/v1/broadcasts \
  -H "Authorization: Bearer $EPOSTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "August product update",
    "subject": "What shipped in August",
    "from": "[email protected]",
    "audience_ids": ["tag_01H..."],
    "html": "<h1>What shipped</h1>"
  }'

It is created as a draft. Nothing sends until you say so, which is the point: a broadcast is not a transactional send and should not be one call away from 50,000 recipients.

audience_ids are tag ids from /v1/tags. Leave it empty to address every subscribed contact.

Send

curl -X POST https://api.epostix.com/v1/broadcasts/{id}/send \
  -H "Authorization: Bearer $EPOSTIX_API_KEY"

Pre-send checks run first. If any fail, the request is rejected with 422 and each failure is listed in details, and nothing is sent:

{
  "type": "validation_error",
  "message": "This broadcast did not pass its pre-send checks. Nothing was sent.",
  "details": [
    {"field": "content", "message": "The message has no unsubscribe link", "code": "unsubscribe_link"}
  ]
}

On success you get 202 and the broadcast moves to sending. Delivery happens in the background, so the response tells you it started rather than that it finished.

Test first

curl -X POST https://api.epostix.com/v1/broadcasts/{id}/test \
  -H "Authorization: Bearer $EPOSTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipients": ["[email protected]"]}'

Up to five addresses. A test renders the real content and sends it for real, so use your own addresses.

Cancel

curl -X POST https://api.epostix.com/v1/broadcasts/{id}/cancel \
  -H "Authorization: Bearer $EPOSTIX_API_KEY"

Cancelling a scheduled broadcast stops it before it starts. Cancelling one that is already sending stops the remainder: messages already handed to a mail server are on their way and cannot be recalled.

Scopes

Broadcasts have three, and the split is deliberate.

Scope	Grants
broadcasts:read	List and read
broadcasts:manage	Create, edit and archive drafts
broadcasts:send	Send, test and cancel

The gap between editing a draft and mailing your whole audience is the largest on the API, so broadcasts:send is separate. A key that builds broadcasts from a CMS rarely needs it.

Stats

GET /v1/broadcasts/{id} includes counts once sending has started: accepted, delivered, failed, bounced, unique opens and unique clicks. The same reading rules as Analytics apply, including that bounced is part of failed rather than additional to it.