Create a broadcast

Search Documentation

Search across all developer documentation
broadcasts

Create a broadcast

POST /v1/broadcasts
Auth required api.broadcasts.manage

Composes a broadcast in the draft state, in one of two mutually-exclusive content modes:

  • Template mode — supply template_id (the template slug / file name from GET /v1/templates, e.g. welcome.html, not a UUID) plus optional template_version (defaults to latest) and template_data (shared merge data; per-recipient contact attributes are overlaid at send). Inject a large rendered HTML block as a triple-stache variable ({{{body_html}}}) so it is not HTML-escaped.
  • Inline mode — supply html (raw, fully-rendered content) plus optional text. Inline HTML must satisfy the same caps as templates (≤500 KB, valid UTF-8, at least one HTML tag).

Supplying both template_id and html, or neither, is a 422 validation_failed. subject and preview_text are owned by the broadcast (overridable per send). from_identity, when given, must be one of the org's verified identities (see GET /v1/identities); omit it to send from the default no-reply@<verified-domain> address. topic_id, when given, is the topic name from GET /v1/topics (not a UUID).

Does not send — call POST /v1/broadcasts/{id}/send. Supports the Idempotency-Key header: a duplicate key within 24 h replays the original response.

Request body

Content type: application/json 

{
  "name": "string",
  "template_id": "string",
  "template_version": 0,
  "template_data": {},
  "html": "string",
  "text": "string",
  "audience_kind": "list",
  "audience_id": "00000000-0000-0000-0000-000000000000",
  "topic_id": "string",
  "from_identity": "string",
  "subject": "string",
  "preview_text": "string",
  "acknowledge_no_topic": true
}

Responses

201 Broadcast created (draft) application/json
401 Missing, malformed, or unknown API key application/problem+json
403 Key lacks the required scope or plan limit violated application/problem+json
422 Query parameter or path value failed validation application/problem+json
429 Per-org rate limit exceeded application/problem+json
500 Unexpected server-side failure. The code is internal_error. The request_id field can be quoted to SendOps support to investigate. application/problem+json