Irisend
Docs

Broadcasts

Send one-off or scheduled broadcasts to every contact in an audience, optionally filtered to a topic's subscribers. /broadcasts API reference with examples.

POST/broadcastsCreate a broadcast

segment_id (the audience to send to) or the legacy alias audience_id is required — provide one, and if both are given they must match. from and subject are required; at least one of html/text is required. Pass topic_id to restrict sending to that topic's subscribers, and { send: true, scheduled_at? } to send (or schedule) immediately instead of leaving it as a draft.

curl -X POST https://api.irisend.com/broadcasts \
  -H "Authorization: Bearer $IRISEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "segment_id": "919b2edf-a103-4b9f-bde7-731668bdfd5c",
    "from": "[email protected]",
    "subject": "What shipped this week",
    "html": "<p>Three new things this week...</p>"
  }'
ResponseJSON
{ "object": "broadcast", "id": "4b673957-c9df-4062-a609-f61ba6eeb296" }
GET/broadcastsList broadcasts
curl https://api.irisend.com/broadcasts \
  -H "Authorization: Bearer $IRISEND_API_KEY"
ResponseJSON
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "4b673957-c9df-4062-a609-f61ba6eeb296",
      "name": "What shipped this week",
      "audience_id": "919b2edf-a103-4b9f-bde7-731668bdfd5c",
      "segment_id": "919b2edf-a103-4b9f-bde7-731668bdfd5c",
      "status": "draft",
      "created_at": "2026-09-25T09:00:12.481Z",
      "scheduled_at": null,
      "sent_at": null
    }
  ]
}
GET/broadcasts/:idRetrieve a broadcast

status is one of draft, scheduled, queued (sending, in progress), sent, or canceled.

curl https://api.irisend.com/broadcasts/4b673957-c9df-4062-a609-f61ba6eeb296 \
  -H "Authorization: Bearer $IRISEND_API_KEY"
ResponseJSON
{
  "object": "broadcast",
  "id": "4b673957-c9df-4062-a609-f61ba6eeb296",
  "name": "What shipped this week",
  "audience_id": "919b2edf-a103-4b9f-bde7-731668bdfd5c",
  "segment_id": "919b2edf-a103-4b9f-bde7-731668bdfd5c",
  "from": "[email protected]",
  "subject": "What shipped this week",
  "reply_to": null,
  "preview_text": null,
  "html": "<p>Three new things this week...</p>",
  "text": null,
  "status": "draft",
  "created_at": "2026-09-25T09:00:12.481Z",
  "scheduled_at": null,
  "sent_at": null,
  "topic_id": null
}
PATCH/broadcasts/:idUpdate a broadcast

Only while status is draft.

curl -X PATCH https://api.irisend.com/broadcasts/4b673957-c9df-4062-a609-f61ba6eeb296 \
  -H "Authorization: Bearer $IRISEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "subject": "What shipped this week (updated)" }'
ResponseJSON
{ "object": "broadcast", "id": "4b673957-c9df-4062-a609-f61ba6eeb296" }
POST/broadcasts/:id/sendSend (or schedule) a broadcast

Only a draft broadcast can be sent. Optional scheduled_at (future, ≤30 days out) schedules it instead of sending immediately. This response is the one place in the API that deliberately omits object — it matches Resend's own Send Broadcast response exactly.

curl -X POST https://api.irisend.com/broadcasts/4b673957-c9df-4062-a609-f61ba6eeb296/send \
  -H "Authorization: Bearer $IRISEND_API_KEY"
ResponseJSON
{ "id": "4b673957-c9df-4062-a609-f61ba6eeb296" }
POST/broadcasts/:id/cancelCancel a broadcast

A scheduled broadcast cancels back to draft (fully reversible, nothing sent). A queued (sending) broadcast cancels to a terminal canceled — emails already sent stand.

curl -X POST https://api.irisend.com/broadcasts/4b673957-c9df-4062-a609-f61ba6eeb296/cancel \
  -H "Authorization: Bearer $IRISEND_API_KEY"
ResponseJSON
{ "object": "broadcast", "id": "4b673957-c9df-4062-a609-f61ba6eeb296" }
POST/broadcasts/:id/duplicateDuplicate a broadcast

Works on any status, including sent — the copy is always a fresh draft.

curl -X POST https://api.irisend.com/broadcasts/4b673957-c9df-4062-a609-f61ba6eeb296/duplicate \
  -H "Authorization: Bearer $IRISEND_API_KEY"
DELETE/broadcasts/:idDelete a broadcast

Only draft or scheduled broadcasts can be deleted.

curl -X DELETE https://api.irisend.com/broadcasts/4b673957-c9df-4062-a609-f61ba6eeb296 \
  -H "Authorization: Bearer $IRISEND_API_KEY"
ResponseJSON
{ "object": "broadcast", "id": "4b673957-c9df-4062-a609-f61ba6eeb296", "deleted": true }
GET/broadcasts/:id/recipientsList recipients by outcome

type is required — one of sent, delivered, opened, clicked, bounced, complained, unsubscribed, or suppressed. Optional bounce_type (permanent/transient/undetermined) only applies with type=bounced.

curl https://api.irisend.com/broadcasts/4b673957-c9df-4062-a609-f61ba6eeb296/recipients?type=clicked&limit=20 \
  -H "Authorization: Bearer $IRISEND_API_KEY"
ResponseJSON
{
  "object": "list",
  "has_more": false,
  "data": [
    { "id": "em_9f2K3mQ1zPr7vT6yB4wL0nC", "contact_id": "919b2edf-a103-4b9f-bde7-731668bdfd5c", "email": "[email protected]", "count": 2, "clicked_links": [{ "url": "https://yourdomain.com/changelog", "clicks": 2 }] }
  ]
}
GET/broadcasts/:id/clicked-linksList clicked links

Ranked by total clicks, descending.

curl https://api.irisend.com/broadcasts/4b673957-c9df-4062-a609-f61ba6eeb296/clicked-links \
  -H "Authorization: Bearer $IRISEND_API_KEY"
ResponseJSON
{
  "object": "list",
  "has_more": false,
  "data": [
    { "id": "aHR0cHM6Ly95b3VyZG9tYWluLmNvbS9jaGFuZ2Vsb2c", "url": "https://yourdomain.com/changelog", "clicks": 14, "unique_clicks": 11 }
  ]
}