Broadcasts

Broadcasts are one-to-many marketing emails sent to a segment of contacts. Create a broadcast in draft, then send it immediately or schedule it for later.

Create a broadcast

POST

/v1/broadcasts

Create a new broadcast in draft status.

Request body

Parameter	Type	Description
`name`required	`string`	Internal label for the broadcast.
`from`required	`string`	Sender email address.
`segmentId`required	`string`	ID of the segment to send to.
`subject`required	`string`	Email subject line. Supports template variables.
`html`	`string`	HTML email body.
`text`	`string`	Plain text body. Auto-generated from HTML if omitted.
`topicId`	`string`	Optional topic filter. Only contacts opted into this topic will receive the broadcast.
`replyTo`	`string`	Reply-to address.
`scheduledAt`	`string (ISO 8601)`	Schedule the broadcast for a future time.

cURL

curl -X POST https://api.txtly.com.au/v1/broadcasts \
  -H "Authorization: Bearer tx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "March Newsletter",
    "from": "newsletter@yourdomain.com",
    "segmentId": "seg_abc123",
    "subject": "What is new in March",
    "html": "<h1>March Update</h1><p>Here is what we have been working on...</p>"
  }'

Response — 201 Created

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "March Newsletter",
  "from": "newsletter@yourdomain.com",
  "segmentId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "segmentName": "All Subscribers",
  "topicId": null,
  "replyTo": null,
  "subject": "What is new in March",
  "html": "<h1>March Update</h1><p>Here is what we have been working on...</p>",
  "text": null,
  "status": "draft",
  "scheduledAt": null,
  "sentAt": null,
  "createdAt": "2026-03-21T00:00:00Z"
}

List broadcasts

GET

/v1/broadcasts

List all broadcasts for the current team.

Get a broadcast

GET

/v1/broadcasts/{id}

Retrieve a broadcast by ID.

Update a broadcast

PATCH

/v1/broadcasts/{id}

Update a broadcast's name, from address, subject, body, reply-to, or scheduled time. Same fields as create; all optional.

Send a broadcast

POST

/v1/broadcasts/{id}/send

Trigger sending of a draft broadcast. Moves status from draft to queued, or to scheduled when the broadcast has a future scheduledAt.

Delete a broadcast

DELETE

/v1/broadcasts/{id}

Delete a draft broadcast. Sent broadcasts cannot be deleted.

Broadcast status

Broadcasts follow a linear status progression:

Parameter	Type	Description
`draft`	`status`	Broadcast is being composed. Can be edited or deleted.
`scheduled`	`status`	Broadcast was sent with a future scheduledAt and will be queued automatically when that time arrives.
`queued`	`status`	Broadcast is queued for sending.
`sending`	`status`	Emails are being dispatched to recipients.
`sent`	`status`	All emails have been dispatched. This is a terminal state.

Unsubscribe handling

Every broadcast email automatically gets an unsubscribe footer link and RFC 8058 one-click unsubscribe headers (List-Unsubscribe and List-Unsubscribe-Post), so mail clients can show a native unsubscribe button. The link carries a per-contact token and points to the public unsubscribe endpoint. You do not need to add your own unsubscribe link.

When a recipient unsubscribes, the contact's unsubscribed flag is set and the address is added to your team's suppression list, blocking all future sends — broadcast, transactional, and workflow. Broadcasts also automatically skip unsubscribed contacts, suppressed addresses, and (when a topic is set) contacts who opted out of that topic.