---
title: "Broadcasts"
description: "`broadcasts.preview`, `send`, `list`, `list_all`, `iterate`, `get`, `list_recipients`, `list_all_recipients`, `iterate_recipients`, `get_recipient`, `stats`, `analytics` and `cancel`."
url: "https://openemail.uk/docs/ruby/broadcasts"
area: "Ruby"
category: "Mailbox"
---

# Broadcasts

`broadcasts.preview`, `send`, `list`, `list_all`, `iterate`, `get`, `list_recipients`, `list_all_recipients`, `iterate_recipients`, `get_recipient`, `stats`, `analytics` and `cancel`.

## Every method

**broadcasts.rb**

```
draft = {
  audienceIds: ["aud_4c1b8e2a7d9f05c36b4e8a71"],
  from: "Acme <news@acme.com>",
  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`.

> Every `send` carries an `Idempotency-Key`, yours through `idempotency_key:` or one the gem makes, so a retry after a network failure answers with the broadcast the first attempt created, with `replayed` set to true, instead of sending twice. `preview`, `get`, `cancel` and every read are safe to repeat and are retried.

**schedule_broadcast.rb**

```
broadcast = client.broadcasts.send(
  audienceIds: ["aud_4c1b8e2a7d9f05c36b4e8a71"],
  from: "Acme <news@acme.com>",
  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.

## Merge fields

`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.

## Unsubscribe

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.

## Who is skipped

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`.

> The whole send is checked against the monthly sends of the plan before anything is written, so a broadcast the allowance cannot cover raises 429 `send_quota_exceeded` as `OpenEmail::RateLimitError` and leaves nothing behind. Each copy counts as one send.

## Status and progress

`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.

## Who it reached

`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:`.

| `filter:` | Keeps |
| --- | --- |
| `pending` | Copies still queued, scheduled or sending. |
| `sent` | Copies that went out. |
| `delivered` | Copies the receiving server accepted. |
| `opened` | Copies opened at least once. |
| `not_opened` | Copies sent and never opened. |
| `clicked` | Copies with at least one tracked click. |
| `bounced` | Copies that bounced. |
| `complained` | Copies the person reported as spam. |
| `failed` | Copies that failed or were cancelled. |
| `unsubscribed` | People who unsubscribed after the broadcast went out. |

`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.

> A key limited to particular addresses or domains reaches only the broadcasts sent from an address or domain it holds. `list`, `list_all` and `iterate` leave the others out, and `get`, the recipient methods, `stats` and `cancel` raise 404 `broadcast_not_found` for them.

## Response: a broadcast

`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.

- `id` (String): The durable handle, `brd_` followed by 24 hex characters.
- `status` (String): `scheduled`, `queued`, `sending`, `sent`, `cancelled` or `failed`. `OpenEmail::BROADCAST_STATUSES` names each one.
- `mode` (String): `live` or `test`, from the key that created it. The copies of a test broadcast are marked sent and delivered to nobody.
- `source` (String): Where it was started: `api` for a key, `oauth` for a connected app, `composer` for the app, `mcp` for an assistant.
- `audienceIds` (Array<String>): The audiences it was sent to, each once.
- `from` (String): The address every copy is sent from.
- `subject` (String): The subject as written, merge fields and all. Empty when a template supplies the subject.
- `counts` (Hash): `recipients` is the estimate taken at `send`. `created` counts the copies written, `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.
- `lastError` (String or nil): Why the broadcast failed, or the most recent copy that could not be written and why. It is nil while nothing has gone wrong.
- `scheduledAt` (String or nil): ISO-8601 UTC, when the sending is due to start. It is nil for a broadcast sent straight away.
- `startedAt` (String or nil): ISO-8601 UTC, when the sending reached the first people.
- `completedAt` (String or nil): ISO-8601 UTC, when the last person was reached. Copies can still be waiting to go after it.
- `cancelledAt` (String or nil): ISO-8601 UTC, when `cancel` stopped it.
- `createdAt` (String): ISO-8601 UTC, when `send` was called. Fixes the list order.
- `updatedAt` (String): ISO-8601 UTC, bumped as the sending moves on.

## Response: a recipient row

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`.

- `emailId` (String): The `msg_` id of this person’s copy. `get_recipient` reads it with its content, and `emails.get` reads it as a sent email, as the List and get page describes.
- `contactId` (String or nil): The contact it went to, or nil when the contact has been deleted since.
- `email` (String): The address the copy went to.
- `name` (String or nil): The name on the contact.
- `status` (String): The state of the copy: `queued`, `scheduled`, `sending`, `sent`, `failed` or `cancelled`.
- `sentAt` (String or nil): ISO-8601 UTC, when the copy went out.
- `deliveredAt` (String or nil): ISO-8601 UTC, when the receiving server accepted it, the first `email.delivered`.
- `bouncedAt` (String or nil): ISO-8601 UTC, when it bounced, the first `email.bounced`.
- `complainedAt` (String or nil): ISO-8601 UTC, when the person reported it as spam, the first `email.complained`.
- `failure` (String or nil): Why the copy failed, when it did.
- `opens` (Integer): Opens recorded, without the ones image proxies and scanners make. 0 when tracking was off.
- `firstOpenAt` (String or nil): ISO-8601 UTC, the first open.
- `clicks` (Integer): Clicks recorded on tracked links, without scanners.
- `firstClickAt` (String or nil): ISO-8601 UTC, the first click.
- `unsubscribedAt` (String or nil): ISO-8601 UTC, when this person unsubscribed from one of the broadcast’s audiences after it went out, through its link or otherwise.