Broadcasts

Every broadcast in this workspace, newest first, one page at a time, each with live counts. audienceId keeps the ones that were sent to that audience, among others or alone.

The individual messages are not here. List them with GET /emails?broadcastId=.

A key limited to particular addresses or domains lists only the broadcasts sent from an address or domain it holds.

Requires the emails:read scope.

Sends one message to everybody in one or more audiences, as a separate copy for each person. Every copy has exactly one recipient and no cc or bcc, so nobody sees who else it went to, and every copy is an ordinary email with its own msg_ id, events, tracking and webhooks. GET /emails?broadcastId= lists them. Copies are not filed in the Sent folder: the broadcast is the record.

The call answers 202 straight away with the broadcast queued, or scheduled when scheduledAt is set, and the sending happens in the background, 50 people at a time. Read GET /broadcasts/{id} for status and counts as it goes.

WHO GETS IT. Every contact in at least one of audienceIds, counted once however many of them hold it, except a contact that has unsubscribed from every one of the chosen audiences it is in, and except an address on the suppression list. A contact added to one of the audiences after this call but before the sending reaches it is included. counts.recipients is the estimate taken now, and POST /broadcasts/preview returns the same count without sending anything.

QUOTA. The whole send is checked against the plan's monthly sends before anything is written. A broadcast the allowance cannot cover is refused with 429 send_quota_exceeded and leaves nothing behind. Each copy counts as one send.

PERSONALISATION. subject, html and text take merge fields, filled in for each person: {{firstName}}, {{lastName}}, {{name}}, {{email}}, {{unsubscribeUrl}}. Each takes a fallback after a bar, such as {{firstName|there}}, used when the contact has no value for it. The values come from the contact: the first name is the first word of its name and the last name is the rest. They are escaped in html, and any other {{…}} is left as written. With template, the same values are passed as props, but only the props the template declares, so a template that declares none of them is sent unchanged.

UNSUBSCRIBE. Every copy carries List-Unsubscribe and List-Unsubscribe-Post: List-Unsubscribe=One-Click, which is what lets a mail client offer its own unsubscribe button and what the large mailbox providers require of bulk mail. An html or text body that does not place {{unsubscribeUrl}} itself gets a one-line footer with the link. A template is sent as it is, so put {{unsubscribeUrl}} in the template. The link opens a page with an Unsubscribe button, and following it marks the person unsubscribed in every audience this broadcast was sent to (unsubscribedAt on GET /audiences/{id}/contacts). Their other audiences, their contact and mail sent to them one message at a time are not affected.

LIMITS. 1 to 10 audiences and up to 8 tags, and every copy also carries the tag broadcast_id. No attachments, cc, bcc, translation or encryption. The body comes from html and or text, or from template, never both.

IDEMPOTENCY. Send an Idempotency-Key and a retry with the same key answers 200 with the broadcast the first call created, with replayed: true and Idempotency-Replayed: true, instead of sending again. The same key with a different body is a 422 idempotency_key_reuse. Without a key, sending the same body twice sends the broadcast twice.

Requires the emails:send and audiences:read scopes.

The numbers POST /broadcasts would work from, without sending anything or writing anything: how many people it would reach, how many are skipped because they have unsubscribed, and how many because their address is suppressed. A contact in several of the audiences counts once.

The count is taken at the moment of the call. Contacts who join or leave before the send starts change it.

Requires the audiences:read scope.

The numbers behind the Analytics tab of the Broadcasts page, in one request: how the live broadcasts sent inside a window did, added up and as a series cut to grain, plus one row per broadcast so they can be compared.

A copy counts when it was sent, or written if it has not gone yet, inside the window, and everything that happened to it afterwards counts with it, so an open today of a copy sent last week is in a 30 day window but not in a 1 day one. Test mode broadcasts are left out. totals and series cover the broadcasts in broadcastIds, or every one when it is left out, and broadcasts always lists every broadcast in the window. The series counts each person once, at the first time it happened to them.

A key limited to particular addresses or domains reads only broadcasts sent from an address or domain it holds, and the rest are left out as if they did not exist.

Requires the emails:read scope.

One broadcast with counts read live from its copies, which makes this the call to poll while it sends. status settles on sent once every copy handed over has gone out or failed, and on failed or cancelled when it stopped early.

A key limited to particular addresses or domains reads only broadcasts sent from an address or domain it holds. Any other broadcast answers 404 broadcast_not_found, as if it did not exist.

Requires the emails:read scope.

Everybody the broadcast went to, one row per copy, sorted by address: the copy id, its status, when it was sent and delivered, whether it bounced or was reported as spam, how often it was opened and clicked, and whether the person unsubscribed after it went out.

Opens and clicks leave out image proxies and link scanners, and stay 0 when the broadcast was sent with tracking off. Keyset paging: pass nextCursor back as cursor, with the same filter and q.

A key limited to particular addresses or domains reads only broadcasts sent from an address or domain it holds. Any other broadcast answers 404 broadcast_not_found, as if it did not exist.

Requires the emails:read scope.

One person's copy: the same row GET /broadcasts/{id}/recipients lists, plus the subject, HTML and text exactly as that person received them, with the merge fields filled in and their own unsubscribe link. The HTML is from before open and click tracking was added.

A key limited to particular addresses or domains reads only broadcasts sent from an address or domain it holds. Any other broadcast answers 404 broadcast_not_found, as if it did not exist.

Requires the emails:read scope.

How the broadcast performed: copies sent, delivered, bounced, reported as spam and failed, and how many people opened, clicked and unsubscribed, as totals and as a series cut to grain. The series counts each person once, at the first time it happened to them, so it adds up to the totals.

Send days or minutes to also read what happened lately: window then counts the copies delivered, bounced, reported, opened, clicked and unsubscribed inside it, and series keeps only its buckets. totals always covers the whole broadcast.

A key limited to particular addresses or domains reads only broadcasts sent from an address or domain it holds. Any other broadcast answers 404 broadcast_not_found, as if it did not exist.

Requires the emails:read scope.

Stops a broadcast that is scheduled, queued or sending, including one that has reached everybody while some copies are still waiting to go. Nobody else is added, and every copy still waiting to go is cancelled. A copy already being handed over finishes, and copies that have gone cannot be recalled, so counts.sent keeps them. No body.

Cancelling a cancelled broadcast answers it as it stands, so a retry is safe.

A key limited to particular addresses or domains cancels only broadcasts sent from an address or domain it holds. Any other broadcast answers 404 broadcast_not_found, as if it did not exist.

Requires the emails:send scope.