Broadcasts API

Send one-to-many campaigns to subscribed contacts using the same queue, suppression list, and delivery events as regular email sends.

How Broadcasts Work

A broadcast starts as a draft. When you send or schedule it, SMTPfast snapshots your selected audience, skips unsubscribed and suppressed addresses, creates one email per recipient, and queues each message for delivery.

Broadcasts are meant for marketing and product updates. They must include an unsubscribe token before they can send.

Audiences can be all subscribed contacts or one manual contact segment. Monthly broadcast limits are tied to your package: Free includes 2, Starter includes 10, Growth includes 50, and Scale includes 200.

Use {{unsubscribe_url}} or {{{RESEND_UNSUBSCRIBE_URL}}} in the markdown, HTML, or text body.

Personalization

Tokens are resolved for each recipient at send time. Add a fallback after a pipe when a value may be blank.

markdown

# Hi {{contact.first_name|there}},

Your workspace is ready.

You are receiving this at {{contact.email}}.

Unsubscribe: {{unsubscribe_url}}

Broadcast Object

json

{
  "object": "broadcast",
  "id": "clx_broadcast123",
  "name": "May product update",
  "audience": "segment",
  "audience_meta": { "segment_id": "seg_product" },
  "from": "[email protected]",
  "reply_to": null,
  "subject": "New features for {{contact.first_name|there}}",
  "status": "draft",
  "scheduled_at": null,
  "queued_at": null,
  "sent_at": null,
  "recipient_count": 0,
  "metrics": {
    "total": 0,
    "delivered": 0,
    "opened": 0,
    "clicked": 0,
    "delivery_rate": 0,
    "open_rate": 0,
    "click_rate": 0
  },
  "created_at": "2026-05-05T12:00:00.000Z",
  "updated_at": "2026-05-05T12:00:00.000Z"
}

GET/v1/broadcasts

List broadcasts in newest-updated order. Use status and q query parameters to filter the list.

Parameters

Parameter	Type	Required	Description
status	string	No	all, draft, scheduled, queued, sent, or canceled
q	string	No	Search by name, subject, or from address
limit	number	No	Number of broadcasts to return, up to 100
page	number	No	Page number for pagination

Response

json

{
  "object": "list",
  "data": [
    {
      "id": "clx_broadcast123",
      "name": "May product update",
      "status": "draft",
      "metrics": { "total": 0, "delivered": 0 }
    }
  ],
  "has_more": false,
  "status_counts": { "draft": 1 }
}

POST/v1/broadcasts

Create a draft broadcast. You can save partial drafts, target all contacts or a manual segment, then update the campaign before sending.

Request Body

json

{
  "name": "May product update",
  "audience": "segment",
  "segment_id": "seg_product",
  "from": "[email protected]",
  "subject": "New features for {{contact.first_name|there}}",
  "markdown": "# Hi {{contact.first_name|there}},\n\nHere is what changed.\n\nUnsubscribe: {{unsubscribe_url}}"
}

Response

json

{
  "object": "broadcast",
  "id": "clx_broadcast123",
  "name": "May product update",
  "status": "draft"
}

GET/v1/broadcasts/:id

Retrieve a broadcast with rollup metrics, recent recipients, recipient events, and link click counts.

PATCH/v1/broadcasts/:id

Update a draft or scheduled broadcast. Updating a scheduled broadcast cancels the old schedule and returns it to draft.

Request Body

json

{
  "subject": "Updated subject",
  "preview_text": "A short inbox preview"
}

POST/v1/broadcasts/:id/test

Queue a test email to one address using sample personalization data.

Request Body

json

{
  "to": "[email protected]"
}

Response

json

{
  "object": "email",
  "id": "email_abc123",
  "status": "queued"
}

POST/v1/broadcasts/:id/send

Send immediately or schedule within 30 days. The send creates a recipient snapshot from the selected audience and queues one email per eligible contact.

Only verified sending domains can send broadcasts. Monthly email quota and monthly broadcast quota are checked before recipients are queued.

Request Body

json

{
  "scheduled_at": "2026-05-12T14:00:00.000Z"
}

Response

json

{
  "object": "broadcast",
  "id": "clx_broadcast123",
  "status": "scheduled",
  "recipients": 1240,
  "skipped": 18,
  "batch_id": "batch_abc123"
}

POST/v1/broadcasts/:id/cancel

Cancel a scheduled broadcast that has not started sending. Delayed queue jobs are removed where possible.

DELETE/v1/broadcasts/:id

Delete a draft broadcast. Sent, queued, scheduled, and canceled broadcasts are retained for audit history.