Broadcasts

Every copy is an ordinary send

A broadcast is never one message with a thousand recipients. It is expanded into one message per contact, and each of them goes through the same accept path as a single POST /v1/emails:

• The suppression list — account-wide and the stream’s own. A suppressed contact is skipped and counted in progress.suppressed.
• Your account’s daily warmup cap and monthly allowance. Every copy spends one of each; there is no separate price and no way round them.
• The pre-send content lint, and the verified-domain check on the sender.
• The delivery record: every copy has its own msg_ id, events and waybill, and appears in the message log.

Each copy carries a one-click List-Unsubscribe header and a visible unsubscribe link added to the body, both pointing at that one message. Pressing either suppresses the address on the broadcast’s stream.

Each contact is sent to exactly once. The copy and the broadcast’s progress are written in the same transaction, under a per-contact idempotency key, so a restart mid-send carries on after the last contact done and never mails anybody twice.

Never on the transactional stream

A broadcast goes out on the built-in announcements stream unless you name another stream you created. It can never use transactional: the API refuses with 422 transactional_stream, and the database refuses it too.

That is the point of the separation. Somebody who unsubscribes from your release notes, or reports one as spam, is suppressed on the announcements stream only — their password resets, receipts and sign-in codes keep arriving. A hard bounce is still account-wide, because a dead mailbox is dead on every stream.

Merge fields

Content is either a stored template (by slug or tpl_ id) or an inline subject with html and/or text — one or the other, never both. Tags are filled per contact from:

A template is pinned to its latest published version when the send starts, so publishing an edit halfway through does not change what the second half of the list receives. Escaping follows the same rules as any template: values are escaped in HTML, not in the subject or the text.

What stops a broadcast

These exist because a broadcast shares a sending IP with every other account on it. They are tighter than anything on a single send.

Create a draft

// A draft. Nothing is sent until send().
const draft = await posthaste.broadcasts.create({
  name: 'Terms of service update',
  list: listId,
  from: 'Acme <[email protected]>',
  template: 'terms-update', // a stored template, by slug or tpl_ id
})

// Your own team only, up to five. Not auto-retried: each call mails again.
const { data } = await posthaste.broadcasts.test(draft.id, ['[email protected]'])

await posthaste.broadcasts.send(draft.id) // or { scheduledAt: '2026-09-25T09:00:00Z' }

// Later: progress is a row read, delivery is counted from the messages.
const b = await posthaste.broadcasts.get(draft.id)
b.status // 'sending'
b.progress // { targeted, accepted, suppressed, failed, failures }
b.delivery // { inFlight, delivered, bounced, complained, failed, unsubscribed }

An account may hold 50 unsent drafts; a 51st is 409 too_many_drafts.

Test, then send

Sends the broadcast to up to five addresses, and every one of them must belong to somebody on your account’s team — anyone else is 422 not_a_team_member, so this cannot be used to mail strangers. The subject is prefixed [Test], merge fields come from the contact with that address or else from the first person on the list, and a test is not counted in the broadcast’s progress. It is a real send through the same checks, reported per address.

Starts it now, or at scheduledAt (ISO-8601, up to 30 days ahead). Everything that would make the whole send fail is checked here, while you are looking, rather than discovered halfway through.

# Try it on your own team first — up to five people, all on this account
curl -X POST https://api.posthastemail.dev/v1/broadcasts/brd_Vn4Ks8Qp2Rt6Wx0Yz3Ab5C/test \
  -H "authorization: Bearer $POSTHASTE_KEY" \
  -H "content-type: application/json" \
  -d '{"to": ["[email protected]"]}'

# 200 {"data":[{"to":"[email protected]","id":"msg_7Qw2Er4Ty6Ui8Op0As1Df3"}]}

# Then send it — now, or at a time up to 30 days ahead
curl -X POST https://api.posthastemail.dev/v1/broadcasts/brd_Vn4Ks8Qp2Rt6Wx0Yz3Ab5C/send \
  -H "authorization: Bearer $POSTHASTE_KEY" \
  -H "content-type: application/json" \
  -d '{"scheduledAt": "2026-09-25T09:00:00Z"}'

# 202 { "id": "brd_…", "status": "scheduled", "reviewState": "not_required", … }

States, pausing and cancelling

Pausing takes effect within one recipient, not one batch: every copy re-reads the broadcast under a lock before it is written. Cancelling stops everything still to come; mail already accepted stays sent.

A broadcast whose list is deleted before it finishes is canceled with list_deleted; one rejected in review is canceled with rejected_in_review.

Progress and delivery

The list is newest first, keyset-paginated with limit (1–100, default 25) and before. One broadcast adds delivery, counted from the messages themselves, so it is the same answer the message log gives.

GET /v1/broadcasts/brd_Vn4Ks8Qp2Rt6Wx0Yz3Ab5C

200 {
  "id": "brd_Vn4Ks8Qp2Rt6Wx0Yz3Ab5C",
  "status": "paused",
  "pauseReason": "daily_limit",
  "reviewState": "not_required",
  "startedAt": "2026-09-25T09:00:04.118Z",
  "progress": {
    "targeted": 1840,
    "accepted": 1203,
    "suppressed": 31,
    "failed": 6,
    "failures": { "missing_field:plan": 6 }
  },
  "delivery": {
    "inFlight": 12,
    "delivered": 1180,
    "bounced": 9,
    "complained": 0,
    "failed": 2,
    "unsubscribed": 4
  },
  …
}

Change or delete a draft

Only a draft can be edited; anything else is 409 not_a_draft. Switching between a template and inline content clears the other side. A draft can be deleted, and so can a canceled broadcast that sent nothing; one that sent mail is 409 broadcast_has_history, because its record is what was sent.

A key with broadcasts:write can mail everybody on a list. Give it only to the service that runs your announcements — see authentication.