textstring
The plain text body. Can use the per-contact variables below.
Broadcasts
Create a broadcast
Create a draft email to one audience. Nothing is sent until you call send.
POST
/v1/broadcastsAPI keyA broadcast is one email sent to every subscribed contact in an audience, one message per contact. Creating it only saves a draft. Start it with Send a broadcast. See Broadcasts.
Off by default
Cloudflare Email Service is for transactional email; bulk marketing is not permitted. Broadcasts only work in projects with broadcastsEnabled: true, and each one is capped at BROADCAST_MAX_RECIPIENTS (500 unless the mailer sets another value). Use them for small lists of people who opted in.
Body parameters
The audience to send to.
The sender, as "Name <address>" or a bare address. Checked against the project's allowed domains and senders now, the same way as Send an email. There is no fallback to the project's default sender.
1 to 998 characters. Can use the per-contact variables below.
The HTML body. Can use the per-contact variables below. Values inserted with {{…}} are HTML-escaped; {{{…}}} inserts them as is.
Per-contact variables
subject, html and text are rendered once per contact with the template syntax ({{name}}, {{#if}}, {{#each}}). The values available are:
| Variable | Value |
|---|---|
{{first_name}} | The contact's firstName, or empty. |
{{last_name}} | The contact's lastName, or empty. |
{{email}} | The contact's address. |
{{unsubscribe_url}} | The contact's one-click unsubscribe link. Only set when the mailer has a TRACKING_SECRET. |
any key in data | Each top-level key of the contact's data, for example {{plan}}. |
first_name, last_name, email and unsubscribe_url win over keys with the same name in data. See Unsubscribe.
Response
Status 201 with the broadcast.
idstring
The broadcast ID, for example bc_01K6C3D9G2J4L7N0Q3S5U8W1YZ.
projectIdstring
audienceIdstring
fromstring
The sender address, lowercased, without the display name.
fromNamestring | null
The display name from from, if you gave one.
subjectstring
htmlstring
textstring | null
status'draft' | 'scheduled' | 'sending' | 'sent' | 'canceled'
Always draft on create.
scheduledAtstring | null
When a scheduled broadcast starts.
startedAtstring | null
When sending began.
completedAtstring | null
When the last contact was processed.
totalnumber
Subscribed contacts in the audience when sending was started. 0 for a draft.
sentnumber
Emails queued so far. This counts emails handed to the send queue, not deliveries.
createdAtstring
updatedAtstring
Errors
| Status | Code | When |
|---|---|---|
| 400 | invalid_body | A field is missing or malformed, or from is not a valid address. |
| 403 | broadcasts_disabled | The project doesn't have broadcasts enabled. |
| 403 | invalid_sender | from is not on the project's allowed domains or senders. |
| 404 | audience_not_found | No audience with that ID in this project. |