Audiences and broadcasts

Keep a list of contacts and send one email to all of them, with unsubscribe handled for you.

Broadcasts are for email you send to many people at once, such as a product update. They use the same sending, quota, domain and review checks as every other email. For one-to-one email such as receipts and sign-in links, send directly instead.

1. Make an audience and add contacts

curl https://api.sendsend.email/v1/audiences \
  -H "Authorization: Bearer $SENDSEND_API_KEY" \
  -d '{"name":"Customers"}'

curl https://api.sendsend.email/v1/audiences/aud_…/contacts/import \
  -H "Authorization: Bearer $SENDSEND_API_KEY" \
  -d '{"contacts":[{"email":"maria@example.com","first_name":"Maria"}]}'

Keys need the contacts:manage scope. Importing never resubscribes someone who unsubscribed.

2. Create a broadcast

In the dashboard, pick a starting point (announcement, product update, newsletter, welcome, invitation or blank) and edit it block by block with a live preview. You can also write the HTML yourself, or send a design to the API and we build the HTML for you.

Write it once and personalise with {{{FIRST_NAME|there}}}. The text after the bar is used when a contact has no first name. Your own fields work the same way once you create them as contact properties.

Send to part of an audience

A segment is a saved filter over an audience: people on the Pro plan, who joined in the last 30 days, who have not opened anything, who are subscribed to a topic. Try rules out first with a live count, then pick the segment on the broadcast. Who matches is worked out as each batch is sent, and unsubscribed people are never included.

3. Send it

Call send, now or with scheduled_at. Sending happens in the background, one message per contact. If your allowance or daily limit runs out, the broadcast pauses and tells you why; send it again to continue without repeating anyone.

Test subject lines or content

Add ab_test when you create a broadcast and it becomes a split test. Your own subject and content are version A, and each entry in variants is another version that replaces whatever it sets (subject, preview_text, html, text or design). You can add up to three.

{
  "audience_id": "aud_…",
  "from": "Acme <news@mail.acme.com>",
  "subject": "What’s new this month",
  "html": "<p>…</p>",
  "ab_test": {
    "variants": [{ "subject": "Three things we shipped" }],
    "test_percent": 20,
    "wait_hours": 4,
    "winner_by": "opens"
  }
}

When you send, test_percent of the audience (5 to 50) is divided between the versions. After wait_hours we count opens (or clicks), pick the best version, and send it to everyone else. Nobody gets two emails, and a tie or no data goes to version A. The stats show each version’s results and the winner.

• The winner is chosen by opens or clicks, so the sending domain needs that tracking turned on, or sending is refused with an explanation. Opens are approximate because some mail apps load images for the reader.
• A test needs enough people to mean something. With fewer than about 1,000 in the audience, the result is mostly chance.
• You can cancel while it waits. Nothing more is sent.

See how it did

Open Stats on a broadcast, or call the stats endpoint: delivered, bounced, complaints, unsubscribes it caused, and, with tracking on for the domain, unique opens and clicks and the links people clicked. Opens are approximate because some mail apps load images for the reader.

Unsubscribing

• Every message carries a working unsubscribe link and the one-click unsubscribe headers that Gmail and Yahoo expect. If you leave the link out, we add a footer link.
• Opening the link shows a confirm button, so mail scanners cannot unsubscribe people by accident.
• Give a broadcast a topic and only subscribed contacts get it, and its link removes them from that topic only.