Create Broadcast

Create a new broadcast. A broadcast is one message sent to a segment of contacts. Unless you pass send: true, the broadcast is created as a draft; call Send Broadcast to deliver it.

POST/broadcasts

Requires an API key with broadcasts:write permission.

Body Parameters

segment_idstring

The segment ID (UUID) of contacts to send this broadcast to. You may use audience_id as a legacy alias; provide at least one of these fields. If both are given, segment_id takes precedence.

audience_idstring

Legacy alias for segment_id.

fromstringrequired

Sender email address. Use "Name <email@example.com>" format for a friendly name.

subjectstringrequired

Email subject.

htmlstring

HTML content of the broadcast. Either html or text is required.

textstring

Plain text content of the broadcast. Either html or text is required.

reply_tostring | string[]

Reply-to email address(es).

namestring

A friendly internal name for the broadcast (not visible to recipients).

topic_idstring

Optional topic ID (UUID) to scope the broadcast. Only contacts subscribed to this topic will receive it.

preview_textstring

Inbox preview text.

sendboolean

Set to true to send right after creation, or to schedule it when scheduled_at is also given. The key then needs both broadcasts:write and broadcasts:send; without broadcasts:send the request fails and no draft is created.

scheduled_atstring

Natural language date or ISO 8601 timestamp for sending later. Only valid with send: true.

Response Fields

idstring

The ID of the newly created broadcast.

curl -X POST 'https://api.postflare.dev/broadcasts' \
  -H 'Authorization: Bearer sk_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "segment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "from": "Acme <newsletter@acme.com>",
    "subject": "Our Monthly Newsletter",
    "html": "<p>Hello!</p>",
    "name": "April Newsletter"
  }'

const response = await fetch('https://api.postflare.dev/broadcasts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_xxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    segment_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    from: 'Acme <newsletter@acme.com>',
    subject: 'Our Monthly Newsletter',
    html: '<p>Hello!</p>',
    name: 'April Newsletter',
  }),
});

const data = await response.json();

Response

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