Broadcasts

draft = {  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 = client.broadcasts.preview(draft)puts reach[:recipients], reach[:unsubscribed], reach[:suppressed] broadcast = client.broadcasts.send(draft) latest = client.broadcasts.get(broadcast[:id])while %w[scheduled queued sending].include?(latest[:status])  sleep 5  latest = client.broadcasts.get(broadcast[:id])end client.broadcasts.iterate_recipients(broadcast[:id]) do |copy|  puts copy[:email], copy[:status], copy[:opens], copy[:clicks]end bounced = client.broadcasts.list_recipients(broadcast[:id], filter: "bounced")bounced.items.each { |row| puts "#{row[:emailId]} #{row[:email]}" } copy = client.broadcasts.get_recipient(broadcast[:id], "msg_01dad25067bc4dac966d515d")puts copy[:subject], copy[:bouncedAt] stats = client.broadcasts.stats(broadcast[:id], grain: "day")puts stats.dig(:totals, :opened), stats.dig(:totals, :clicked), stats.dig(:totals, :unsubscribed) lately = client.broadcasts.stats(broadcast[:id], days: 1)puts lately.dig(:window, :opened) later = client.broadcasts.send(draft, scheduledAt: "P1D")client.broadcasts.cancel(later[:id]) history = client.broadcasts.list(audience_id: draft[:audienceIds].first)puts latest[:status], latest.dig(:counts, :sent), history.items.size month = client.broadcasts.analytics(days: 30)month[:broadcasts].each do |row|  puts row[:subject], row[:sent], row[:opened]end

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, and 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.

broadcast = client.broadcasts.send(  audienceIds: ["aud_4c1b8e2a7d9f05c36b4e8a71"],  from: "Acme <[email protected]>",  subject: "Doors open on Friday",  text: "Hi {{firstName|there}}, doors open at nine. Unsubscribe: {{unsubscribeUrl}}",  scheduledAt: Time.now + 3600,  idempotency_key: "doors-open-2026-10") puts broadcast[:id], broadcast[:status], broadcast[:replayed]

The fields of a broadcast are keyword arguments or one Hash, and keep the API’s camelCase names (audienceIds:, scheduledAt:). idempotency_key: and api_key: are options of the call and are never sent as fields. Keywords passed beside a Hash are merged into it, so send(draft, scheduledAt: "P1D") sends the same draft a day later. scheduledAt: takes a Time, a DateTime, an ISO 8601 string or a duration such as PT2H, and a Time goes out as a UTC instant. preview sends only audienceIds from what you give it, so it takes the same Hash as send. A response is a Hash with Symbol keys, so broadcast[:status] reads the status.

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, as a Hash with id and optionally version, props and slots. 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 its 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 audiences.list_contacts shows it in the unsubscribedAt of their row, as the Audiences page describes. 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 as OpenEmail::ValidationError.

get reads counts live from the copies, so poll it while a broadcast sends, with sleep between calls as the sample above does. 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 as OpenEmail::ConflictError, and cancelling a cancelled broadcast returns it as it stands.

list_recipients returns one OpenEmail::Page of the people a broadcast went to, one row per copy, sorted by address, with items, has_more? and next_cursor. list_all_recipients walks every page into one Array, and iterate_recipients yields one copy at a time to a block, fetching the next page only when the loop asks for it. Without a block it returns an Enumerator. limit: goes from 1 to 200 and defaults to 50, and a cursor: goes back with the same filter: and q:.

OpenEmail::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. Pass the emailId of a row as email_id. 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, both as OpenEmail::NotFoundError.

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 the zone offset_minutes: east of UTC. Pass Time.now.utc_offset / 60 for the local zone. It counts each person once, at the first time it happened to them, so it adds up to the totals.

Pass days: or minutes: to stats to also read what happened lately. window then counts what was 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 nil.

send, get and cancel each return one of these, a Hash with Symbol keys, and send adds replayed. list returns an OpenEmail::Page of them, newest first, and list_all and iterate walk every page. preview returns a Hash with audienceIds, recipients, unsubscribed and suppressed. list_recipients returns an OpenEmail::Page of recipient rows, get_recipient returns one row with its content, and stats returns a Hash with broadcastId, grain, totals, window and series. analytics returns a Hash with totals, series and one row per broadcast in broadcasts. Times are ISO 8601 strings, which Time.iso8601 parses.

Each row of list_recipients, list_all_recipients and iterate_recipients, as a Hash with Symbol keys. The Hash get_recipient returns adds subject, html and text.