Broadcasts

A broadcast is one send to every subscribed contact in an audience — each recipient gets an individual email with personalized merge tags and their own unsubscribe link. Broadcast recipients count against your normal plan quota.

Create a draft

POST/api/v1/broadcasts

curl -X POST https://www.noticeapi.com/api/v1/broadcasts \
  -H "Authorization: Bearer ntc_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "audienceId": "AUDIENCE_ID",
    "from": "Acme News <[email protected]>",
    "subject": "June changelog",
    "html": "<h1>Hi {{{FIRST_NAME}}}</h1><p>...</p><p><a href=\"{{{UNSUBSCRIBE_URL}}}\">Unsubscribe</a></p>"
  }'

Field	Type	Description
`audienceId`required	string	The audience to send to (subscribed contacts only).
`from`required	string	Verified domain sender; display names supported.
`subject`required	string	Broadcast subject line.
`html / text`required	string	At least one. Merge tags: {{{FIRST_NAME}}}, {{{LAST_NAME}}}, {{{EMAIL}}}, {{{UNSUBSCRIBE_URL}}}.
`replyTo`	string	Reply-to address.

Send it

POST/api/v1/broadcasts/:id/send

Quota, daily limits, and domain verification are checked up front; the fan-out then runs in the background. Poll the broadcast until status flips to sent.

curl -X POST https://www.noticeapi.com/api/v1/broadcasts/BROADCAST_ID/send \
  -H "Authorization: Bearer ntc_xxxxxxxxxxxxxxxxxxxx"

# → { "ok": true, "status": "sending", "recipients": 1240 }

Unsubscribe is not optional

Every broadcast email carries a signed unsubscribe link (auto-appended if your HTML omits the merge tag) plus one-click List-Unsubscribe headers — Gmail and Yahoo require them for bulk senders. Unsubscribes apply immediately, appear in stats, and never affect your transactional sends.

Stats

GET/api/v1/broadcasts/:id

curl https://www.noticeapi.com/api/v1/broadcasts/BROADCAST_ID \
  -H "Authorization: Bearer ntc_xxxxxxxxxxxxxxxxxxxx"

# → { "broadcast": { "status": "sent", ... },
#     "stats": { "accepted": 1240, "delivered": 1201,
#                "opened": 512, "clicked": 128,
#                "bounced": 9, "unsubscribed": 4 } }