API · Broadcasts

Create Broadcast

Create a broadcast with HTML or plain text content (requires full access). Recipients are checked for suppressions and subscription preferences before sending, and personalized unsubscribe links are included.

POST/broadcastsFull access

Request parameters

Parameter	Type	Description
`Idempotency-Key` header · optional	`string` 1–256 characters	Makes the request safe to retry. See Idempotency.
`name` body · optional	`string \| null`	Broadcast name, up to 1000 characters.
`from` body · required	`string`	Sender email address, up to 1000 characters.
`subject` body · required	`string`	Email subject, up to 998 characters.
`html` body · optional	`string \| null`	HTML content, up to 256 KiB; provide nonempty HTML or text when creating the broadcast.
`text` body · optional	`string \| null`	Plain text content, up to 256 KiB; provide nonempty text or HTML when creating the broadcast.
`preview_text` body · optional	`string \| null`	Email preview text, up to 1000 characters.
`reply_to` body · optional	`string \| (string)[]`	Up to 50 valid reply-to addresses, with the first address limited to 1000 characters.
`segment_id` body · optional	`string \| null`	Recipient segment ID; null or omission selects all contacts unless audience_id is supplied.
`audience_id` body · optional	`string \| null`	Alternative recipient segment ID used when segment_id is null or omitted.
`topic_id` body · optional	`string \| null`	Topic whose subscription preferences are checked before delivery.
`send` body · optional	`boolean`	Whether to send immediately or at scheduled_at; false keeps the broadcast as a draft.
`scheduled_at` body · optional	`string \| null`	Send time, used only when send is true, in ISO 8601 or natural language up to 30 days ahead with UTC as the default timezone. Send time in ISO 8601 or natural language, up to 30 days ahead, using UTC when unzoned; past times send immediately and rescheduling requires a future time.

Request example

Set OPENSEND_BASE_URL=https://api.example.com and OPENSEND_API_KEY=os_replace_me on your server.

bash

curl -X POST "$OPENSEND_BASE_URL/broadcasts" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"from":"hello@example.com","subject":"Product update","html":"<p>Hello.</p>","name":"Product update"}'

Response

201 · application/json. Example IDs stand for IDs returned by your installation.

json

{
  "object": "broadcast",
  "id": "YOUR_ID"
}

Behavior and errors

Recipients are resolved when sending begins. Global and topic opt-outs and team suppressions are excluded; preferences are rechecked before provider submission. Deleted targets refuse sending instead of widening the audience.

Use a full-access credential. Resource IDs belong to your team; an unknown or foreign resource returns 404. See authentication, errors, rate limits, and compatibility for the shared contract.