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 <news@acme.com>",
    "subject": "June changelog",
    "html": "<h1>Broadcast Campaigns API Guide & Mass Newsletter Dispatch</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`	string	Provide at least one unless you provide reactSource. Merge tags: {{{FIRST_NAME}}}, {{{LAST_NAME}}}, {{{EMAIL}}}, {{{UNSUBSCRIBE_URL}}}.
`contentMode`	"html" \| "react"	Set react when you provide React Email source.
`reactSource`	string \| null	One static React Email component, up to 200KB.
`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.

The dashboard accepts rich text, HTML, or the same safe single-file React Email source as the template editor. NoticeAPI renders React Email into stored HTML and text before it sends.

Edit a draft

PATCH/api/v1/broadcasts/:id

Update the audience, sender, subject, tracking, or content while the broadcast is a draft. Cancel a scheduled broadcast before you edit it.

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 } }