Skip to content
Esc
↑↓navigate↵open⌘Jpreview

Create a broadcast

POST/broadcasts
Authorization
AuthorizationBearer token · headerrequired

A BillionSend API key (bs_…).

Request body
requiredapplication/json
namestring

Internal name shown in the dashboard

segment_idstring<uuid>

Segment to send to; omitted means every contact of the team

fromstringrequired

Sender, "Name <user@domain>"; the domain must be one of the team's own verified domains when the broadcast is sent: sending from an address on the shared inbox domain answers 403

subjectstringrequired

Subject line; supports {{{FIRST_NAME|there}}} merge fields

min length 1 · max length 998
htmlstring

HTML body; include {{{UNSUBSCRIBE_URL}}} for the opt-out link

textstring

Plain-text body; at least one of html/text is required

reply_tostring | string[]

Reply-To address or list

Show properties
Any of:
string
string
string[]
Array of string
string
preview_textstring

Inbox preview (preheader) text

topic_idstring<uuid> | null

Topic id; only contacts subscribed to it receive the broadcast

sendboolean

true sends (or schedules) immediately instead of saving a draft

scheduled_atstring

Deliver later (requires send: true): ISO 8601 with offset or relative like "in 1 hour"

Responses
200

Broadcast created (and scheduled when send: true)

idstring<uuid>required
finishes_atstring | null

When the last email is expected to go out (ISO 8601); null when unknown

estimatedboolean

finishes_at is an estimate that moves as other sends come in

Allowed:true
warningobject
Show properties
codestringrequired

paced: more than the capacity available now; queued_behind: other sends go first

Allowed:pacedqueued_behind
daysintegerrequired

Days the send spans

messagestringrequired
400

Broadcast state conflict

statusCodenumberrequired
namestringrequired
messagestringrequired
401

Missing, malformed, unknown or revoked API key

statusCodenumberrequired
namestringrequired
messagestringrequired
403

Restricted API key, sending paused, or a From on the shared inbox domain

statusCodenumberrequired
namestringrequired
messagestringrequired
404

Not found

statusCodenumberrequired
namestringrequired
messagestringrequired
422

Validation error

statusCodenumberrequired
namestringrequired
messagestringrequired
429

Over the rate limit (rate_limit_exceeded, with Retry-After)

statusCodenumberrequired
namestringrequired
messagestringrequired
Try it
Server
Authorization
Bodyapplication/json
Request
curl -X POST 'https://api.billionsend.com/broadcasts' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "segment_id": "0dbbf761-5b2d-4647-8bfa-2b714456749c",
  "from": "string",
  "subject": "string",
  "html": "string",
  "text": "string",
  "reply_to": "string",
  "preview_text": "string",
  "topic_id": "646807af-5da6-43aa-83d3-8ac1d15ab4e5",
  "send": true,
  "scheduled_at": "string"
}'
Response
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "finishes_at": "string",
  "estimated": true,
  "warning": {
    "code": "paced",
    "days": 0,
    "message": "string"
  }
}

Was this page helpful?