openemail broadcasts

Returns the numbers send would work from, without sending or writing anything: recipients, the people a broadcast to these audiences would reach now, unsubscribed, the contacts skipped because they have unsubscribed from every one of these audiences they are in, and suppressed, the subscribed contacts skipped because their address is on the suppression list. A contact in several of the audiences counts once.

The count is taken at the moment of the call, so contacts who join or leave before a send change it. Only --audience-ids is sent, so you can pass the same object you are about to give send.

Creates a broadcast: one message sent to every contact in the audiences you name, 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. emails.list({ broadcastId }) lists them. Copies are not filed in the Sent folder, because the broadcast is the record.

The promise settles straight away with the broadcast queued, or scheduled when you pass --scheduled-at, and the sending happens in the background, 50 people at a time. Poll get to follow status and counts as it goes.

Who gets it: every contact in at least one of --audience-ids, counted once however many of them hold it, except a contact that has unsubscribed from every one of those 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 at the call, and preview returns the same count without sending.

subject, html and text take merge fields, filled in from each contact: {{firstName}}, {{lastName}}, {{name}}, {{email}} and {{unsubscribeUrl}}. Each takes a fallback after a bar, so {{firstName|there}} reads there for a contact with no name. The first name is the first word of the contact's name and the last name is the rest. Values are escaped in html, and any other {{…}} is left as written. With template, the same values are passed as props, but only the ones the template declares.

Every copy carries the one-click unsubscribe headers mail clients and the large mailbox providers look for. An html or text body that does not place {{unsubscribeUrl}} itself gets a one-line footer with the link, while a template is sent as it is, so put {{unsubscribeUrl}} in the template. Following the link marks the person unsubscribed in every audience this broadcast went to; their other audiences, their contact and mail sent to them one message at a time are not affected.

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

Returns one page of the broadcasts in the workspace, newest first, each with live counts. --audience-id keeps the ones that were sent to that audience, alone or beside others.

Paging is keyset: --limit takes 1 to 100 and defaults to 25, and nextCursor, the id of the last broadcast on the page, goes back as --cursor while hasMore is true. Send the same --audience-id with every page.

The individual messages are not here. List the copies of one broadcast with emails.list({ broadcastId }).

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

Returns one broadcast with counts read live from its copies, which makes this the call to poll while it sends.

status moves from scheduled or queued to sending and settles on sent once every copy handed over has gone out or failed. It reads sending for as long as copies are still waiting, even after the last person was reached and completedAt was set. cancelled and failed are the other two ends, and on failed lastError says why: the from address can no longer be sent from, the template stopped resolving, the plan ran out part way, the sending itself kept failing, or not one copy could be written.

counts.recipients is the estimate taken when it was created. created is the copies written, one per person reached, skipped the people passed over because their address was suppressed by then, and failedToQueue the people whose copy could not be written. queued, sending, sent, failed and cancelled count the copies by the state each one is in now.

Resolves with the totals and a series for one broadcast. totals counts copies sent, delivered, bounced, complained (reported as spam) and failed, pending for the ones still waiting, and people who opened, clicked and unsubscribed, with opens and clicks as event counts. series is sparse and oldest first: one bucket per grain in which something happened, counting each person once at the first time it happened to them, so it adds up to the totals.

Pass days or minutes to also read what happened lately. window then counts the copies delivered, bounced, reported as spam, opened, clicked and unsubscribed inside it, and series keeps only its buckets, while totals still covers the whole broadcast. Without either, window is null.

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

A copy counts when it was sent 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 add up the broadcasts named in --broadcast-ids, or every one when it is left out, while broadcasts always lists every broadcast in the window, newest first.

series is sparse and oldest first: a bucket in which nothing happened has no entry, so a chart must fill the gaps. It counts each person once, at the first time it happened to them. grain sets the bucket width and the key shape, YYYY-MM-DD, YYYY-MM-DDTHH or YYYY-MM-DDTHH:MM, and --offset-minutes shifts the boundaries so days break where the reader's day does. The window starts at the beginning of its oldest bucket, reported as since, and ends now, reported as until.

Resolves one page of the people a broadcast went to, one row per copy, sorted by address. Each row says the copy's 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 from one of the broadcast's audiences after it went out.

Opens and clicks leave out image proxies and link scanners, and stay 0 when the broadcast went out with tracking off. emailId is the copy's msg_ id, which getRecipient reads with its content and emails.get reads as a sent email.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

Resolves with one copy: the same row listRecipients gives, 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.

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 is cancelled. A copy already being handed over finishes, and copies that have gone cannot be recalled, so counts.sent keeps them and counts.cancelled shows what was stopped.

Once every copy has gone out there is nothing left to stop, and the call throws 409 broadcast_not_cancellable. A failed broadcast with copies still waiting can be cancelled to stop them, and one with nothing waiting is refused the same way. Cancelling a broadcast that is already cancelled resolves with it as it stands, so the call is safe to repeat, and the SDK retries it after a network failure.