Broadcasts

A broadcast sends the same email, personalized, to every subscribed contact of an audience or segment. Use it for newsletters, product updates and announcements.

#1. Create a draft

curl -X POST https://api.usend.et/broadcasts \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "October update",
    "segment_id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
    "from": "Acme <[email protected]>",
    "subject": "What is new in October",
    "html": "<p>Hi {{{FIRST_NAME|there}}},</p><p>Here is what we shipped.</p><p><a href=\"{{{UNSUBSCRIBE_URL}}}\">Unsubscribe</a></p>",
    "text": "Hi {{{FIRST_NAME|there}}}, here is what we shipped. Unsubscribe: {{{UNSUBSCRIBE_URL}}}"
  }'

{ "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794" }

segment_id (or audience_id, the older name) and from are required to create a draft. subject and html or text are required before sending. The from address must be on a verified domain. Drafts can be edited with PATCH /broadcasts/{id} and deleted with DELETE /broadcasts/{id}.

#Personalize

Placeholders are replaced for each contact:

Add a fallback after a | for empty values: {{{FIRST_NAME|there}}} renders there when the contact has no first name. Values are HTML-escaped. Names are case-insensitive, and other placeholders are left as they are.

#Unsubscribe

Every broadcast email carries List-Unsubscribe and List-Unsubscribe-Post: List-Unsubscribe=One-Click headers, so Gmail, Yahoo and other clients show their own unsubscribe button and can unsubscribe in one click (RFC 8058). Include {{{UNSUBSCRIBE_URL}}} in your content as well, so readers can unsubscribe from the email itself.

The link opens a confirmation page hosted by usend. Unsubscribed contacts are marked unsubscribed: true and a contact.unsubscribed webhook event is sent.

#2. Send a test

Send one copy to yourself before sending to everyone:

curl -X POST https://api.usend.et/broadcasts/49a3999c-0ce1-4ea6-ab68-afcd6dc2e794/test \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{ "to": "[email protected]" }'

The test email's subject starts with [Test], and placeholders are filled with sample data (first name Test, last name Recipient). A test is a normal email: it counts toward your quota and follows the sandbox rules, and the response contains its email ID.

#3. Send or schedule

curl -X POST https://api.usend.et/broadcasts/49a3999c-0ce1-4ea6-ab68-afcd6dc2e794/send \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "tomorrow at 9am" }'

Leave out scheduled_at to send now. It accepts the same formats as email scheduling, up to 30 days ahead. A broadcast can be sent only once, and only while it is a draft.

usend then creates one email per contact. Unsubscribed contacts and contacts on your suppression list are skipped. Each email is a normal email with its own ID, events and webhooks, and its webhook payloads include broadcast_id.

#Staged sending

Broadcasts to more than 1,000 contacts go out in two stages to protect your reputation:

1. A first wave goes to 5% of the audience (at least 100 contacts).
2. 30 minutes later, usend checks the wave. If its hard-bounce rate is at most 5% and its complaint rate at most 0.3%, the rest is sent.
3. Otherwise the broadcast becomes paused and the organization's owners are emailed. A high bounce rate usually means the list is old or was not collected with consent.

#Status and stats

GET /broadcasts/{id} returns the broadcast with its status and stats:

stats counts the broadcast's emails: total, sent, delivered, bounced, opened, clicked and unsubscribed.

See the Broadcasts API reference.