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.

For the product overview, read the broadcast email API guide. For the unsubscribe flow, read how NoticeAPI handles unsubscribe requests.

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>",
    "tracking": { "opens": true, "clicks": true }
  }'

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.
`tracking`	object	Optional { opens, clicks } override for every email in this broadcast. Omitted fields use the sending domain's defaults.
`scheduledAt`	ISO timestamp	Optional. Creates the broadcast as scheduled, up to 30 days ahead.

Send it

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

Draft broadcasts can be sent immediately. 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 }

Schedule it

POST/api/v1/broadcasts/:id/schedule

Schedule or reschedule a draft for delivery up to 30 days ahead. The platform's minute scheduler checks due broadcasts and runs the same send guardrails used by immediate sends.

curl -X POST https://www.noticeapi.com/api/v1/broadcasts/BROADCAST_ID/schedule \
  -H "Authorization: Bearer ntc_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "scheduledAt": "ISO_TIMESTAMP_UP_TO_30_DAYS_FROM_NOW" }'

# → { "ok": true, "broadcast": { "status": "scheduled", "scheduledAt": "..." } }

Cancel a scheduled broadcast

POST/api/v1/broadcasts/:id/cancel

Canceling a scheduled broadcast returns it to draft state. No email is sent until you schedule it again or call the send endpoint.

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

# → { "ok": true, "broadcast": { "status": "draft", "scheduledAt": null } }

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,
#                "bounced": 9, "unsubscribed": 4 } }