Broadcasts

import time from openemail import openemailfrom openemail.types import BroadcastCreate draft: BroadcastCreate = {    'audienceIds': ['aud_4c1b8e2a7d9f05c36b4e8a71'],    'from': 'Acme <[email protected]>',    'subject': '{{firstName|Hello}}, the September release is out',    'html': '<p>Hi {{firstName|there}},</p><p>Here is what changed this month.</p>',    'text': 'Hi {{firstName|there}}, here is what changed this month. Unsubscribe: {{unsubscribeUrl}}',    'tags': {'campaign': 'release-2026-09'},} reach = openemail.broadcasts.preview(draft)print(reach['recipients'], reach['unsubscribed'], reach['suppressed']) broadcast = openemail.broadcasts.send(draft) latest = openemail.broadcasts.get(broadcast['id'])while latest['status'] in ('scheduled', 'queued', 'sending'):    time.sleep(5)    latest = openemail.broadcasts.get(broadcast['id']) for copy in openemail.broadcasts.iterate_recipients(broadcast['id']):    print(copy['email'], copy['status'], copy['opens'], copy['clicks']) bounced = openemail.broadcasts.list_recipients(broadcast['id'], filter='bounced')if bounced['items']:    content = openemail.broadcasts.get_recipient(broadcast['id'], bounced['items'][0]['emailId'])    print(content['subject'], content['bouncedAt']) stats = openemail.broadcasts.stats(broadcast['id'], grain='day')print(stats['totals']['opened'], stats['totals']['clicked'], stats['totals']['unsubscribed']) lately = openemail.broadcasts.stats(broadcast['id'], days=1)print(lately['window']['opened'] if lately['window'] else None) month = openemail.broadcasts.analytics(days=30)for row in month['broadcasts']:    print(row['subject'], row['sent'], row['opened']) later = openemail.broadcasts.send({**draft, 'scheduledAt': 'P1D'})openemail.broadcasts.cancel(later['id']) history = openemail.broadcasts.list(audience_id=draft['audienceIds'][0])print(latest['status'], latest['counts']['sent'], len(history['items']))

A broadcast 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. list_recipients lists them with what happened to each. The copies are not filed in the Sent folder, because the broadcast is the record.

send returns straight away with the broadcast queued, or scheduled when you pass scheduledAt, and the sending runs in the background. send needs emails:send and audiences:read, preview needs audiences:read, list, list_all, iterate, get, list_recipients, list_all_recipients, iterate_recipients, get_recipient, stats and analytics need emails:read, and cancel needs emails:send.

subject, html and text are filled in for each person from their contact. {{firstName}} is the first word of the contact name, {{lastName}} the rest of it, {{name}} the whole name, {{email}} the address the copy goes to and {{unsubscribeUrl}} the link that unsubscribes them.

Every field takes a fallback after a bar, used when the contact has no value for it, so {{firstName|there}} becomes "there" for a contact saved without a name. Values are escaped in html, and any other {{…}} is left exactly as written.

Pass template instead of html and text to send a stored template. The same five values reach it as props, but only the props the template declares, so a template that declares firstName gets it and one that does not is never refused for it. Anything in template.props goes to every copy alike.

Every copy carries the one-click unsubscribe headers that let a mail client show its own unsubscribe button, which 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 exactly as it is, so put {{unsubscribeUrl}} in the template.

Unsubscribing marks the person unsubscribed in every audience that broadcast went to, and AudienceContactResource.unsubscribedAt shows it on audiences.list_contacts. They stay in the audience and in the address book, their other audiences are untouched, and mail sent to them one message at a time still goes. Taking them out of the audience and adding them again makes them subscribed afresh.

A broadcast reaches every contact in at least one of audienceIds, once however many of them hold it. It skips a contact that has unsubscribed from every one of those audiences it is in, and an address on the suppression list after a bounce or a complaint, or because somebody added it there. A contact added to one of the audiences after send but before the sending reaches it is included.

preview returns the same numbers without sending: recipients, unsubscribed and suppressed. A send that would reach nobody raises 422 no_recipients.

get reads counts live from the copies, so poll it while a broadcast sends. status moves from scheduled or queued to sending and settles on sent once every copy handed over has gone out or failed. It stays sending while copies are still waiting, even after completedAt says the last person was reached. failed means the whole broadcast stopped, and 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.

cancel stops a broadcast that is scheduled, queued or sending. Nobody else is added and every copy still waiting is cancelled, while copies that have gone cannot be recalled. Once every copy has gone, cancel raises 409 broadcast_not_cancellable, and cancelling a cancelled broadcast returns it as it stands.

list_recipients returns one page of the people a broadcast went to, one row per copy, sorted by address, as a dict with items, hasMore and nextCursor. list_all_recipients walks every page into one list and iterate_recipients yields one copy at a time, fetching the next page only when the loop asks for it. limit goes from 1 to 200 and defaults to 50, and a cursor goes back with the same filter and q.

BROADCAST_RECIPIENT_FILTERS names each filter, and q searches the address and the name, ignoring case. Opens and clicks leave out image proxies and link scanners, and stay 0 when the broadcast went out with tracking off.

get_recipient(id, email_id) returns one copy: the same row, plus 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. An email_id that is not a copy of this broadcast raises 404 recipient_not_found, and an unknown broadcast raises 404 broadcast_not_found.

stats returns the totals and a series. totals counts copies sent, delivered, bounced, complained and failed, with 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 (minute, hour or day, defaulting to hour) in which something happened, cut in offset_minutes east of UTC. It counts each person once, at the first time it happened to them, so it adds up to the totals.

get and cancel each return one of these, and send returns a SentBroadcastResource, the same fields plus replayed, which is True when the answer is the broadcast an earlier call with the same idempotency key created. list returns a page of them, a dict with items, hasMore and nextCursor, newest first, and list_all and iterate walk every page. preview returns a BroadcastPreviewResource with audienceIds, recipients, unsubscribed and suppressed. list_recipients returns a page of BroadcastRecipientResource rows, get_recipient a BroadcastRecipientContentResource and stats a BroadcastStatsResource.

Each row of list_recipients, list_all_recipients and iterate_recipients. BroadcastRecipientContentResource, from get_recipient, adds subject, html and text.

• broadcasts.preview()Full reference
• broadcasts.send()Full reference
• broadcasts.list()Full reference
• broadcasts.list_all()Full reference
• broadcasts.iterate()Full reference
• broadcasts.get()Full reference
• broadcasts.list_recipients()Full reference
• broadcasts.list_all_recipients()Full reference
• broadcasts.iterate_recipients()Full reference
• broadcasts.get_recipient()Full reference
• broadcasts.stats()Full reference
• broadcasts.analytics()Full reference
• broadcasts.cancel()Full reference