Broadcasts

Create a broadcast draft

Create a broadcast campaign draft. Broadcasts can be edited while draft or scheduled, and must include an unsubscribe token before sending.

post/v1/broadcasts

Request

  • Base URL: https://smtpfa.st/api
  • URL: https://smtpfa.st/api/v1/broadcasts
  • Auth: HTTP bearer

Request body

namestring
audience'all_contacts' | 'segment'
segment_idstring

Required when audience is segment

audience_metaAudienceMeta

Details of the audience, such as the segment_id

template_idstring

Not in Resend, and only on create (PATCH ignores it). Start from a template (id or alias): its current content, as the template editor shows it, is copied into the new draft, with declared fallbacks written inline. Fields sent alongside win. name defaults to the template's name.

fromstring email
reply_tostring email nullable
subjectstring
preview_textstring nullable
markdownstring

Markdown body. Must include {{unsubscribe_url}} or {{{RESEND_UNSUBSCRIBE_URL}}} before sending.

htmlstring nullable
textstring nullable
track_opensboolean
track_clicksboolean
send_over_minutesinteger nullable

Not in Resend. Spread the send evenly over this many minutes from the send time (or scheduled_at): recipient i of N goes out at start + i * window / N. 0 sends to everyone at once. 15 to 4320 (72 hours). Useful on a new sending domain or during the first week's warm-up, where each hour of the window must fit the hourly cap; the daily cap still counts the whole send. null clears it.

Example request

{
  "name": "May product update",
  "segment_id": "clx_segment123",
  "audience_meta": {
    "segment_id": "clx_segment123"
  },
  "template_id": "product-update",
  "from": "updates@example.com",
  "subject": "New features for {{contact.first_name|there}}",
  "send_over_minutes": 240
}

Response

Broadcast created

objectstring
idstring required
namestring required
audiencestring
audience_metaAudienceMeta

Details of the audience, such as the segment_id

fromstring nullable
reply_tostring nullable
subjectstring nullable
preview_textstring nullable
htmlstring nullable
textstring nullable
markdownstring nullable
status'draft' | 'scheduled' | 'queued' | 'sending' | 'sent' | 'paused' | 'canceled' | 'failed' required
scheduled_atstring date-time nullable
queued_atstring date-time nullable
sent_atstring date-time nullable
canceled_atstring date-time nullable
archived_atstring date-time nullable

When the broadcast was archived. Archived broadcasts are left out of the list unless archived=true or archived=all.

paused_atstring date-time nullable

Set when the campaign was stopped mid-send by the deliverability guard

pause_reasonstring nullable

Why the campaign was paused, for example the complaint rate that tripped the guard

fanout_completed_atstring date-time nullable

When every recipient of the send had been created

expected_recipientsinteger nullable

Eligible recipients counted when the send was accepted

send_over_minutesinteger

Minutes the send is spread over from its start (scheduled_at, else queued_at); 0 means all at once

track_opensboolean
track_clicksboolean
recipient_countinteger
created_atstring date-time required
updated_atstring date-time required

Example response

{
  "object": "broadcast",
  "id": "clx_broadcast123",
  "name": "May product update",
  "audience": "all_contacts",
  "audience_meta": {
    "segment_id": "clx_segment123"
  },
  "from": "updates@example.com",
  "status": "draft",
  "track_opens": true,
  "track_clicks": true,
  "recipient_count": 1250,
  "metrics": {
    "total": 1250,
    "skipped": 12,
    "handed_off": 1238,
    "sent": 1238,
    "delivered": 1202,
    "opened": 714,
    "clicked": 208,
    "unsubscribed": 3,
    "bounced": 9,
    "complained": 1,
    "delivery_rate": 97.1,
    "open_rate": 59.4,
    "click_rate": 17.3,
    "unsubscribe_rate": 0.2,
    "bounce_rate": 0.7
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.