Send Broadcast

Send a broadcast immediately or schedule it for a future time. Only broadcasts in draft status can be sent.

POST/broadcasts/{broadcast_id}/send

The recipient list is determined when the broadcast is dispatched, not when it is scheduled. A contact added to the segment between scheduling and sending will receive it; one removed will not. A scheduled broadcast produces no emails at all until its time arrives, which is what makes cancelling or deleting it free of consequence.

Requirements

The broadcast's content must contain the {{{RESEND_UNSUBSCRIBE_URL}}} placeholder. It is replaced, per recipient, with a signed unsubscribe link. A broadcast without it is refused with a 400.

What happens next

The broadcast moves to queued and is expanded into one email per eligible contact — one address each, so no recipient sees who else was addressed. Contacts who have unsubscribed from your organisation, or who are not subscribed to the broadcast's topic, are excluded before an email exists for them.

The broadcast reaches sent once every email has been created and handed to the sending queue; sent_at is stamped then, not when this request returns. Delivery itself is reported per recipient, in the broadcast's statistics.

If expansion begins and cannot finish — a quota exhausted partway, content that cannot be read — the broadcast is left at expansion_incomplete. The emails already created are delivered normally; the rest of the segment receives nothing.

Quota

Sending charges one email against your monthly quota for each address the message was actually offered to. A contact excluded for consent before an email existed costs nothing; a suppressed address is charged, because the suppression check is work performed; the undelivered remainder of a cancelled broadcast is not charged. A scheduled broadcast charges nothing until it fires.

A broadcast whose segment is larger than your remaining quota is refused before anything is queued.

Requires a full_access API key.

Path Parameters

broadcast_idstringrequired

The broadcast ID (UUID).

Body Parameters

scheduled_atstring

Schedule the broadcast to be sent later. Accepts ISO 8601 format (e.g. "2024-08-05T11:52:01.858Z") or natural language (e.g. "in 1 hour"). Must be within 30 days from now.

If omitted, the broadcast is queued for immediate delivery.

Response Fields

idstring

The broadcast ID.

curl -X POST 'https://api.postflare.app/broadcasts/d4e5f6a7-b8c9-0123-defa-234567890123/send' \
  -H 'Authorization: Bearer re_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{}'

const response = await fetch(
  'https://api.postflare.app/broadcasts/d4e5f6a7-b8c9-0123-defa-234567890123/send',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer re_xxxxxxxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({}),
  }
);

const data = await response.json();

Response

{
  "id": "d4e5f6a7-b8c9-0123-defa-234567890123"
}