Send a broadcast

Moves a draft broadcast to sending, or to scheduled when you pass scheduledAt. The response comes back straight away; the emails go out in the background.

How sending worksCopy Anchor Link

The mailer's cron runs every 5 minutes. On each run it:

1. Moves scheduled broadcasts whose scheduledAt has passed to sending.
2. Takes up to 10 sending broadcasts and, for each one, the next 100 contacts in the audience.
3. Skips contacts that are unsubscribed or on the suppression list.
4. Sends every other contact their own email, rendered with the per-contact variables.
5. Marks the broadcast sent once a run finds fewer than 100 contacts left.

So a broadcast to 500 contacts takes about five cron runs, around 25 minutes. The first emails go out on the next run after this call, up to 5 minutes later.

Each email:

• goes through the same path as Send an email, so it counts toward the project's rate limit and daily limit;
• has the tag broadcast_id set to the broadcast ID;
• has the idempotency key bc:<broadcast id>:<contact id>, so a contact never gets the same broadcast twice;
• has List-Unsubscribe and List-Unsubscribe-Post: List-Unsubscribe=One-Click headers when the mailer has a TRACKING_SECRET. See Unsubscribe.

If a send hits a rate limit, the run stops there and the next run picks up from the same contact. Any other error on one contact is logged and that contact is skipped.

Path parametersCopy Anchor Link

Body parametersCopy Anchor Link

The body is optional.

ResponseCopy Anchor Link

The broadcast with counts, as in Retrieve a broadcast. status is sending or scheduled. total is the number of subscribed contacts in the audience right now; suppressed contacts are still in this number and are skipped later.

ErrorsCopy Anchor Link