API reference

Broadcasts API

Reference for creating, sending, scheduling, canceling, duplicating and deleting broadcasts.

The broadcasts API manages marketing email sent to a segment. Every endpoint needs a full_access key. For the concepts, including variables, the unsubscribe footer and who is skipped, see Broadcasts.

The broadcast object

JSON

{
  "object": "broadcast",
  "id": "jb4m7q2x5c8v1n6z9w3e0r2t",
  "name": "November newsletter",
  "segment_id": "jd5f2h8k4m7p1r6t9v3x0z2c",
  "audience_id": "jd5f2h8k4m7p1r6t9v3x0z2c",
  "topic_id": null,
  "from": "Acme <news@mail.yourcompany.com>",
  "subject": "What is new at Acme",
  "reply_to": null,
  "preview_text": "Three things we shipped this month",
  "html": "<p>Hi {{{FIRST_NAME|there}}},</p>",
  "text": null,
  "status": "draft",
  "created_at": "2026-11-14T10:00:00.000Z",
  "scheduled_at": null,
  "sent_at": null
}

audience_id always equals segment_id. status is draft, scheduled, queued, sending, sent, canceled or failed. reply_to is an array or null.

Create a broadcast

POST/broadcasts

Creates a draft. Add send: true to send it in the same request.

Field	Type	Required	Description
`name`	string	No	Up to 200 characters. Defaults to the subject, or "Untitled broadcast".
`segment_id`	string	To send	The audience. `audience_id` is accepted as an alias.
`topic_id`	string or null	No	Limits the audience to contacts subscribed to the topic.
`from`	string	To send	An address on a verified domain.
`subject`	string	To send	Up to 998 characters.
`reply_to`	string or string[]	No	Reply-to addresses.
`preview_text`	string	No	Up to 500 characters.
`html`, `text`	string	To send, at least one	The body, with optional variables.
`send`	boolean	No	Send immediately. If validation fails, no draft is created.
`scheduled_at`	string	No	Used only with `send: true`. ISO 8601 or `in 2 hours`, at most 30 days ahead.

Shell

curl -X POST https://api.sooner.dev/broadcasts \
  -H "Authorization: Bearer $SOONER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "November newsletter",
    "segment_id": "jd5f2h8k4m7p1r6t9v3x0z2c",
    "from": "Acme <news@mail.yourcompany.com>",
    "subject": "What is new at Acme",
    "html": "<p>Hi {{{FIRST_NAME|there}}},</p><p>Here is what is new.</p>"
  }'

JSON

{ "id": "jb4m7q2x5c8v1n6z9w3e0r2t" }

Notable errors: not_found for an unknown segment or topic. With send: true, also missing_required_field, invalid_from_address and validation_error, listed under Send a broadcast.

List broadcasts

GET/broadcasts

Returns the project's broadcasts, newest first. Accepts limit and after. See Pagination.

Shell

curl "https://api.sooner.dev/broadcasts?limit=10" \
  -H "Authorization: Bearer $SOONER_API_KEY"

JSON

{
  "object": "list",
  "data": [
    {
      "object": "broadcast",
      "id": "jb4m7q2x5c8v1n6z9w3e0r2t",
      "name": "November newsletter",
      "status": "sent",
      "segment_id": "jd5f2h8k4m7p1r6t9v3x0z2c",
      "audience_id": "jd5f2h8k4m7p1r6t9v3x0z2c",
      "topic_id": null,
      "from": "Acme <news@mail.yourcompany.com>",
      "subject": "What is new at Acme",
      "reply_to": null,
      "preview_text": null,
      "html": "<p>Hi</p>",
      "text": null,
      "created_at": "2026-11-14T10:00:00.000Z",
      "scheduled_at": null,
      "sent_at": "2026-11-14T10:05:00.000Z"
    }
  ],
  "has_more": false
}

Retrieve a broadcast

GET/broadcasts/{id}

Returns one broadcast in the shape above. Notable errors: not_found.

Update a broadcast

PATCH/broadcasts/{id}

Changes a draft. It accepts the same content fields as create, and only the fields you send change. send and scheduled_at are ignored here. Use the send endpoint.

Shell

curl -X PATCH https://api.sooner.dev/broadcasts/jb4m7q2x5c8v1n6z9w3e0r2t \
  -H "Authorization: Bearer $SOONER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "subject": "What is new at Acme this month" }'

JSON

{ "id": "jb4m7q2x5c8v1n6z9w3e0r2t" }

Notable errors: validation_error ("Only drafts can be edited."), not_found.

Send a broadcast

POST/broadcasts/{id}/send

Validates a draft and starts sending it, now or at a scheduled time. Delivery to the segment continues in the background.

Field	Type	Required	Description
`scheduled_at`	string	No	ISO 8601 or `in 2 hours`, at most 30 days ahead. A past time sends immediately.

Shell

curl -X POST https://api.sooner.dev/broadcasts/jb4m7q2x5c8v1n6z9w3e0r2t/send \
  -H "Authorization: Bearer $SOONER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-11-20T09:00:00Z" }'

JSON

{ "id": "jb4m7q2x5c8v1n6z9w3e0r2t" }

Notable errors:

Error	When
`missing_required_field`	No segment, no `from` or `subject`, or neither `html` nor `text`.
`invalid_from_address`	The `from` domain is not verified in this project.
`validation_error`	The broadcast is not a draft, or `scheduled_at` is invalid or more than 30 days away.
`not_found`	Unknown broadcast.

Cancel a broadcast

POST/broadcasts/{id}/cancel

Cancels a broadcast whose status is scheduled. A canceled broadcast cannot be sent again, so duplicate it to reuse the content.

Shell

curl -X POST https://api.sooner.dev/broadcasts/jb4m7q2x5c8v1n6z9w3e0r2t/cancel \
  -H "Authorization: Bearer $SOONER_API_KEY"

JSON

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

Notable errors: validation_error ("Only scheduled broadcasts can be canceled.").

Duplicate a broadcast

POST/broadcasts/{id}/duplicate

Creates a new draft with the same content, named with "(copy)" appended.

JSON

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

Delete a broadcast

DELETE/broadcasts/{id}

Deletes a draft or a canceled broadcast. A scheduled broadcast is canceled and then deleted.

Shell

curl -X DELETE https://api.sooner.dev/broadcasts/jb4m7q2x5c8v1n6z9w3e0r2t \
  -H "Authorization: Bearer $SOONER_API_KEY"

JSON

{ "object": "broadcast", "id": "jb4m7q2x5c8v1n6z9w3e0r2t", "deleted": true }

Notable errors: validation_error ("Sent broadcasts can't be deleted.") for a broadcast that has started, finished or failed.