--- title: "openemail broadcasts" description: "Every command in this namespace, with its arguments, flags and examples." url: "https://openemail.uk/docs/cli/reference/broadcasts" area: "CLI" category: "Reference" --- # openemail broadcasts Every command in this namespace, with its arguments, flags and examples. ## Commands ### `openemail broadcasts preview` Count who a broadcast to some audiences would reach ```bash openemail broadcasts preview --audience-ids [flags] openemail broadcasts preview --data [flags] ``` 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`. - Scopes: `audiences:read`. - Needs a sign-in. **Flags** - `--audience-ids ` (repeatable): 1 to 10 audience ids. One that names no audience in the workspace is a 404 `audience_not_found`. Required, here or in `--data`. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash openemail broadcasts preview --audience-ids aud_4c1b8e2a7d9f05c36b4e8a71,aud_7e3d9a1c5b2f84e06d9a3c51 ``` Read the whole body from a JSON file ```bash openemail broadcasts preview --data @broadcast.json ``` Also available in: API [`POST /broadcasts/preview`](https://openemail.uk/docs/api/reference/broadcasts#post-broadcasts-preview); SDK [`broadcasts.preview()`](https://openemail.uk/docs/sdk/reference/broadcasts#preview). ### `openemail broadcasts send` Send one message to everybody in one or more audiences ```bash openemail broadcasts send --audience-ids --from [flags] openemail broadcasts send --data [flags] ``` 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. - Scopes: `emails:send`, `audiences:read`. - Needs a sign-in. - Asks you to confirm. **Flags** - `--audience-ids ` (repeatable): 1 to 10 audience ids such as `aud_9f2c4b7e1a0d63d84c5f2e7b`. A contact in several of them gets one copy. An id that names no audience in the workspace is a 404 `audience_not_found` and nothing is sent. Required, here or in `--data`. - `--from `: Sender as `news@acme.com`, `Acme ` or `{ email, name }`. It must be an address the key may send as, otherwise 403 `from_address_forbidden`. Required, here or in `--data`. - `--reply-to `: Where replies go, the same for every copy. - `--subject ` (default `""`): Required unless a template supplies it, at most 998 characters. Takes merge fields. - `--html `: HTML body, at most 1,000,000 characters, with merge fields. Without `{{unsubscribeUrl}}` in it an unsubscribe footer is added. - `--text `: Plain text body, at most 1,000,000 characters, with merge fields. Without `{{unsubscribeUrl}}` in it an unsubscribe line is added. - `--template `: A stored template instead of `html` and `text`, never beside them. The merge values reach it as props it declares, such as `firstName` and `unsubscribeUrl`. JSON shaped as `{ id: string, version?: number, props?: Record, slots?: Record }`, inline or from a file with @path. - `--tracking `: Open and link tracking for every copy. A field left out follows the address it is sent from when that address set it, and is on otherwise. JSON shaped as `{ opens?: boolean, clicks?: boolean }`, inline or from a file with @path. - `--tags ` (repeatable, default `{}`): Up to 8 tags, keys of 1 to 64 letters, digits, `_` or `-`, values up to 256 characters. Every copy carries them, plus `broadcast_id`, which the server adds. - `--scheduled-at `: A `Date`, an ISO 8601 instant or a duration such as `PT2H` or `P1D`, in the future and at most 365 days out. Left out, the sending starts straight away. - `--idempotency-key `: Your own key, 1 to 255 characters of letters, digits, `_`, `.`, `:` or `-`. Left out, the SDK makes one for the call, so its own retries never send twice. Sending the same key again answers with the broadcast it created instead of a new one; the same key with a different body is a 422 `idempotency_key_reuse`. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** The required values only ```bash openemail broadcasts send --audience-ids aud_4c1b8e2a7d9f05c36b4e8a71 --from 'Acme ' ``` With optional flags ```bash openemail broadcasts send --audience-ids aud_4c1b8e2a7d9f05c36b4e8a71 --from 'Acme ' --subject '{{firstName|Hello}}, the September release is out' --html '

Hi {{firstName|there}},

Here is what changed this month.

Unsubscribe

' --scheduled-at PT2H ``` Read the whole body from a JSON file ```bash openemail broadcasts send --data @broadcast.json ``` Skip the confirmation, for scripts ```bash openemail broadcasts send --audience-ids aud_4c1b8e2a7d9f05c36b4e8a71 --from 'Acme ' --yes ``` Also available in: API [`POST /broadcasts`](https://openemail.uk/docs/api/reference/broadcasts#post-broadcasts); SDK [`broadcasts.send()`](https://openemail.uk/docs/sdk/reference/broadcasts#send). ### `openemail broadcasts list` List one page of broadcasts, newest first ```bash openemail broadcasts list [flags] ``` 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 ` stops after that many items. - Scopes: `emails:read`. - Needs a sign-in. - Aliases: `ls`. **Flags** - `--audience-id `: Only the broadcasts that included this audience. An id that names no audience answers an empty page. - `--limit ` (default `25`): Rows per page, a whole number from 1 to 100. The server defaults to 25. - `--cursor `: The `nextCursor` from the previous page, a broadcast id. One that names no broadcast in the workspace is a 400 `invalid_cursor`. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** ```bash openemail broadcasts list ``` With optional flags ```bash openemail broadcasts list --audience-id aud_4c1b8e2a7d9f05c36b4e8a71 --limit 10 ``` Walk every page and stop after 100 items ```bash openemail broadcasts list --all --max 100 ``` One JSON object per line when piped ```bash openemail broadcasts list --all > broadcasts.ndjson ``` Also available in: API [`GET /broadcasts`](https://openemail.uk/docs/api/reference/broadcasts#get-broadcasts); SDK [`broadcasts.list()`](https://openemail.uk/docs/sdk/reference/broadcasts#list). ### `openemail broadcasts get` Read one broadcast and how far it has got ```bash openemail broadcasts get [flags] ``` 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. - Scopes: `emails:read`. - Needs a sign-in. - Aliases: `show`, `view`. **Arguments** - `` (required): A `brd_` id from `send` or `list`. **Examples** ```bash openemail broadcasts get brd_5a8c1e3f7b2d94a06c8e1f3b ``` Print the raw JSON ```bash openemail broadcasts get brd_5a8c1e3f7b2d94a06c8e1f3b --json ``` Also available in: API [`GET /broadcasts/{id}`](https://openemail.uk/docs/api/reference/broadcasts#get-broadcasts-id); SDK [`broadcasts.get()`](https://openemail.uk/docs/sdk/reference/broadcasts#get). ### `openemail broadcasts stats` Read how a broadcast performed ```bash openemail broadcasts stats [flags] ``` 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. - Scopes: `emails:read`. - Needs a sign-in. **Arguments** - `` (required): A `brd_` id from `send` or `list`. **Flags** - `--grain ` (default `"hour"`): Bucket width: `minute`, `hour` or `day`, defaulting to `hour`. - `--offset-minutes ` (default `0`): Minutes east of UTC to cut the buckets in, from -840 to 840. Pass `-new Date().getTimezoneOffset()` for the local zone. - `--days `: Reads a window of this many days too, from 1 to 1095. It starts at the beginning of its first `grain` bucket and ends now. - `--minutes `: The window in minutes, from 1 to 1576800, which wins over `days` when both are sent. **Examples** The required values only ```bash openemail broadcasts stats brd_5a8c1e3f7b2d94a06c8e1f3b ``` With optional flags ```bash openemail broadcasts stats brd_5a8c1e3f7b2d94a06c8e1f3b --grain day ``` Print the raw JSON ```bash openemail broadcasts stats brd_5a8c1e3f7b2d94a06c8e1f3b --json ``` Also available in: API [`GET /broadcasts/{id}/stats`](https://openemail.uk/docs/api/reference/broadcasts#get-broadcasts-id-stats); SDK [`broadcasts.stats()`](https://openemail.uk/docs/sdk/reference/broadcasts#stats). ### `openemail broadcasts analytics` Read how broadcasts did over a time window ```bash openemail broadcasts analytics [flags] ``` 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`. - Scopes: `emails:read`. - Needs a sign-in. **Flags** - `--broadcast-ids ` (repeatable): Up to 50 broadcast ids for `totals` and `series` to add up, sent comma separated. Leave it out, or pass an empty array, for every broadcast in the window. An id with no copy in the window adds nothing, and more than 50 is a 422. - `--days ` (default `30`): Window length in days, from 1 to 1095, defaulting to 30. - `--minutes `: Window length in minutes, from 1 to 1576800, which wins over `days` when both are sent. - `--grain ` (default `"day"`): Bucket width: `minute`, `hour` or `day`, defaulting to `day`. - `--offset-minutes ` (default `0`): Minutes east of UTC to cut the buckets in, from -840 to 840, defaulting to 0. Pass `-new Date().getTimezoneOffset()` for the local zone. **Examples** ```bash openemail broadcasts analytics ``` With optional flags ```bash openemail broadcasts analytics --days 90 ``` Print the raw JSON ```bash openemail broadcasts analytics --json ``` Also available in: API [`GET /broadcasts/analytics`](https://openemail.uk/docs/api/reference/broadcasts#get-broadcasts-analytics); SDK [`broadcasts.analytics()`](https://openemail.uk/docs/sdk/reference/broadcasts#analytics). ### `openemail broadcasts list-recipients` List who a broadcast went to and what happened to each copy ```bash openemail broadcasts list-recipients [flags] ``` 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 ` stops after that many items. - Scopes: `emails:read`. - Needs a sign-in. **Arguments** - `` (required): A `brd_` id from `send` or `list`. **Flags** - `--filter `: Keeps one group: `pending`, `sent`, `delivered`, `opened`, `not_opened` (sent and never opened), `clicked`, `bounced`, `complained`, `failed` (failed or cancelled) or `unsubscribed`. `BROADCAST_RECIPIENT_FILTERS` names them. - `--q `: Searches the address and the name, ignoring case. - `--limit ` (default `50`): Page size, from 1 to 200. The server defaults to 50. - `--cursor `: The `nextCursor` of the previous page. Send the same `filter` and `q` with it. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** The required values only ```bash openemail broadcasts list-recipients brd_5a8c1e3f7b2d94a06c8e1f3b ``` With optional flags ```bash openemail broadcasts list-recipients brd_5a8c1e3f7b2d94a06c8e1f3b --filter bounced ``` Walk every page and stop after 100 items ```bash openemail broadcasts list-recipients brd_5a8c1e3f7b2d94a06c8e1f3b --all --max 100 ``` One JSON object per line when piped ```bash openemail broadcasts list-recipients brd_5a8c1e3f7b2d94a06c8e1f3b --all > broadcasts.ndjson ``` Also available in: API [`GET /broadcasts/{id}/recipients`](https://openemail.uk/docs/api/reference/broadcasts#get-broadcasts-id-recipients); SDK [`broadcasts.listRecipients()`](https://openemail.uk/docs/sdk/reference/broadcasts#listRecipients). ### `openemail broadcasts get-recipient` Read one person's copy of a broadcast ```bash openemail broadcasts get-recipient [flags] ``` 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. - Scopes: `emails:read`. - Needs a sign-in. **Arguments** - `` (required): A `brd_` id from `send` or `list`. - `` (required): The `emailId` of the copy, from `listRecipients`. **Examples** ```bash openemail broadcasts get-recipient brd_5a8c1e3f7b2d94a06c8e1f3b msg_01dad25067bc4dac966d515d ``` Print the raw JSON ```bash openemail broadcasts get-recipient brd_5a8c1e3f7b2d94a06c8e1f3b msg_01dad25067bc4dac966d515d --json ``` Also available in: API [`GET /broadcasts/{id}/recipients/{emailId}`](https://openemail.uk/docs/api/reference/broadcasts#get-broadcasts-id-recipients-emailid); SDK [`broadcasts.getRecipient()`](https://openemail.uk/docs/sdk/reference/broadcasts#getRecipient). ### `openemail broadcasts cancel` Stop a broadcast that is scheduled, queued or still sending ```bash openemail broadcasts cancel [flags] ``` 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. - Scopes: `emails:send`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): The `brd_` id to cancel. **Examples** ```bash openemail broadcasts cancel brd_5a8c1e3f7b2d94a06c8e1f3b ``` Skip the confirmation, for scripts ```bash openemail broadcasts cancel brd_5a8c1e3f7b2d94a06c8e1f3b --yes ``` Also available in: API [`POST /broadcasts/{id}/cancel`](https://openemail.uk/docs/api/reference/broadcasts#post-broadcasts-id-cancel); SDK [`broadcasts.cancel()`](https://openemail.uk/docs/sdk/reference/broadcasts#cancel).