Broadcasts and unsubscribes
Send to a segment, personalize, and honor unsubscribes.
A broadcast sends one message to a segment of contacts.
- Create contacts and a segment.
POST /contacts,POST /segments, then add contacts withPOST /contacts/{contact_id}/segments/{segment_id}. - Create the broadcast with
POST /broadcasts(it starts as a draft), or write it in the dashboard's visual editor. - Send now or schedule it with
POST /broadcasts/{id}/send.POST /broadcasts/{id}/cancelstops one that has not finished.
Check progress with GET /broadcasts/{id}/recipients and GET /broadcasts/{id}/clicked-links.
Personalization
Write variables as {{{KEY|fallback}}}. The fallback is used when the value is missing or empty. Values are HTML-escaped in the HTML body.
| Variable | Value |
|---|---|
FIRST_NAME, LAST_NAME, EMAIL | The contact's fields. Case-insensitive. A contact. prefix also works. |
RESEND_UNSUBSCRIBE_URL or UNSUBSCRIBE_URL | That contact's unsubscribe link |
| Anything else | A custom contact property, with its property-level fallback |
<p>Hi {{{FIRST_NAME|there}}},</p>
<p><a href="{{{UNSUBSCRIBE_URL}}}">Unsubscribe</a></p>Unsubscribes
Each recipient gets a signed link to a hosted /unsubscribe page, and a preferences page at /preferences for topic opt-outs. The link carries a token signed with UNSUBSCRIBE_SECRET, and it never expires, so an old email keeps working. It only lets that one contact unsubscribe or edit their topic subscriptions.
Set UNSUBSCRIBE_SECRET to 32 or more random bytes. Changing it breaks links in mail you already sent.
An unsubscribed contact is skipped on later sends. Topics let you split lists: a contact can opt out of one topic and stay subscribed to the others. Manage them with /topics and /contacts/{contact_id}/topics.
Rate
BROADCAST_SEND_RATE sets emails per second. It defaults to 1, the SES sandbox limit. Raise it to your SES quota once production access is approved. The dispatcher runs from /internal/broadcasts/dispatch. If the team is paused, or the daily or monthly quota is reached, the broadcast is held and resumes later. See Rate limits and quotas.