--- title: "openemail audiences" description: "Every command in this namespace, with its arguments, flags and examples." url: "https://openemail.uk/docs/cli/reference/audiences" area: "CLI" category: "Reference" --- # openemail audiences Every command in this namespace, with its arguments, flags and examples. ## Commands ### `openemail audiences list` List one page of the workspace audiences ```bash openemail audiences list [flags] ``` Returns one page of the audiences in the workspace, with the default audience first and the rest newest first. Paging is keyset: `--limit` takes 1 to 100 and defaults to 25, and `nextCursor` goes back as `--cursor` while `hasMore` is true, so every audience is reachable. `builtin` tells the default audience apart from the ones you made. It is `default` on exactly one row per workspace, the audience that holds every contact, and null on everything else. Branch on `builtin` rather than on the name, which anybody can change. `contactCount` is counted at the moment of the read, so two reads either side of a `contacts.create` disagree by one. 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: `audiences:read`. - Needs a sign-in. - Aliases: `ls`. **Flags** - `--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, an audience id. One that names no audience 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 audiences list ``` Walk every page and stop after 100 items ```bash openemail audiences list --all --max 100 ``` One JSON object per line when piped ```bash openemail audiences list --all > audiences.ndjson ``` Also available in: API [`GET /audiences`](https://openemail.uk/docs/api/reference/audiences#get-audiences); SDK [`audiences.list()`](https://openemail.uk/docs/sdk/reference/audiences#list). ### `openemail audiences growth` Read how audiences grew over a time window ```bash openemail audiences growth [flags] ``` Returns the numbers behind the growth chart on the Audiences page in one request. For each audience it reports `total`, the contacts in it now, `before`, how many of those joined before the window, `added`, how many joined inside it, `subscribed`, how many of them are still subscribed, `unsubscribed`, how many unsubscribed inside the window through a broadcast link, and `buckets`, when they joined and unsubscribed, cut to `grain`. `totals` sums the audiences read. An audience records the date each contact joined it and never the date one left. A series therefore counts the contacts still in the list today by the date they joined, and it never falls: a contact who joined inside the window and was removed since is not in it at all. Read it as the growth of the list as it stands, not as a history of every change. `totals.contacts` counts each person once, however many of the audiences they are in. `totals.memberships` adds the lists up, and the default audience holds every contact, so a person in two other audiences counts three times there. `totals.subscribed` counts each person still subscribed to at least one of the audiences read, which is who a broadcast to them would reach, and `totals.unsubscribed` adds up the unsubscribes inside the window. `totals.busiest` is the bucket with the most joins, or null. `buckets` is sparse and oldest first: a bucket in which nobody joined or unsubscribed has no entry, so a chart must fill the gaps. `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: `audiences:read`. - Needs a sign-in. **Flags** - `--audience-ids ` (repeatable): Up to 50 audience ids to read, sent comma separated. Leave it out, or pass an empty array, to read every audience in the workspace, the default one included. An id that is not an audience of this workspace is a 404 `audience_not_found` on `--audience-ids`, 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. Takes precedence over `days`, and only useful below a day with a finer `grain`. - `--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 audiences growth ``` With optional flags ```bash openemail audiences growth --days 90 --grain day ``` Print the raw JSON ```bash openemail audiences growth --json ``` Also available in: API [`GET /audiences/growth`](https://openemail.uk/docs/api/reference/audiences#get-audiences-growth); SDK [`audiences.growth()`](https://openemail.uk/docs/sdk/reference/audiences#growth). ### `openemail audiences get` Read one audience by id ```bash openemail audiences get [flags] ``` Returns a single audience in the same shape as `list`, with a fresh `contactCount`. This is the cheap way to watch a count move without pulling the contacts behind it. The id is the one from `list` or `create`, such as `aud_9f2c4b7e1a0d63d84c5f2e7b`. An id from another workspace is a 404 rather than a 403, since the API never tells you that something exists somewhere you cannot see. - Scopes: `audiences:read`. - Needs a sign-in. - Aliases: `show`, `view`. **Arguments** - `` (required): Audience id such as `aud_9f2c4b7e1a0d63d84c5f2e7b`. **Examples** ```bash openemail audiences get aud_9f2c4b7e1a0d63d84c5f2e7b ``` Print the raw JSON ```bash openemail audiences get aud_9f2c4b7e1a0d63d84c5f2e7b --json ``` Also available in: API [`GET /audiences/{id}`](https://openemail.uk/docs/api/reference/audiences#get-audiences-id); SDK [`audiences.get()`](https://openemail.uk/docs/sdk/reference/audiences#get). ### `openemail audiences create` Create an audience ```bash openemail audiences create --name [flags] openemail audiences create --data [flags] ``` Makes a new, empty audience in the workspace and returns it with its id. `name` is trimmed and must then be 1 to 120 characters. `description` is optional free text for whoever reads the list later. The audience comes back with `builtin` null and `contactCount` zero. Only the default audience carries a `builtin`, and it cannot be made or copied here. Names are not checked for duplicates, so two calls with the same name make two audiences. Fill it with `audiences.addContact`, one contact at a time, and the contacts must already be in the book. - Scopes: `audiences:write`. - Needs a sign-in. - Aliases: `new`, `add`. **Flags** - `--name `: Display name, trimmed, 1 to 120 characters. Not unique. Required, here or in `--data`. - `--description `: What the audience is for. Leave it out to create the audience without one. - `--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 audiences create --name 'Product updates' ``` With optional flags ```bash openemail audiences create --name 'Product updates' --description 'Customers who asked to hear about releases' ``` Read the whole body from a JSON file ```bash openemail audiences create --data @audience.json ``` Also available in: API [`POST /audiences`](https://openemail.uk/docs/api/reference/audiences#post-audiences); SDK [`audiences.create()`](https://openemail.uk/docs/sdk/reference/audiences#create). ### `openemail audiences update` Rename an audience or change its description ```bash openemail audiences update [flags] ``` Changes the fields you send and leaves the rest alone. A key you leave out keeps its stored value and an explicit null clears it, so `{ description: null }` empties the description while `{}` changes nothing. The default audience can be renamed like any other, and renaming it does not change `builtin` or what it holds. `builtin` itself cannot be set, moved or cleared from here. The id never changes, and membership is untouched. - Scopes: `audiences:write`. - Needs a sign-in. - Aliases: `edit`. **Arguments** - `` (required): Audience id such as `aud_9f2c4b7e1a0d63d84c5f2e7b`. **Flags** - `--name `: New display name, trimmed, 1 to 120 characters. - `--description `: New description. Null clears it. - `--data `: The whole `patch` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** With optional flags ```bash openemail audiences update aud_9f2c4b7e1a0d63d84c5f2e7b --name 'Release notes' ``` Print the raw JSON ```bash openemail audiences update aud_9f2c4b7e1a0d63d84c5f2e7b --name 'Release notes' --json ``` Also available in: API [`PATCH /audiences/{id}`](https://openemail.uk/docs/api/reference/audiences#patch-audiences-id); SDK [`audiences.update()`](https://openemail.uk/docs/sdk/reference/audiences#update). ### `openemail audiences delete` Delete an audience and keep its contacts ```bash openemail audiences delete [flags] ``` Deletes the audience and drops every membership it held, in one transaction. The contacts themselves are not touched: they stay in the address book, in the default audience, and in any other audience they were in. The default audience cannot be deleted. The call is refused with 409 `audience_immutable` on `id`, because it is what makes the book readable as a list. Delete the contacts instead if you mean to empty it. There is no undo, and a new audience with the same name comes back empty. - Scopes: `audiences:write`. - Needs a sign-in. - Asks you to confirm. - Aliases: `rm`, `del`, `remove`. **Arguments** - `` (required): Audience id such as `aud_9f2c4b7e1a0d63d84c5f2e7b`. Not the default audience. **Examples** ```bash openemail audiences delete aud_9f2c4b7e1a0d63d84c5f2e7b ``` Skip the confirmation, for scripts ```bash openemail audiences delete aud_9f2c4b7e1a0d63d84c5f2e7b --yes ``` Also available in: API [`DELETE /audiences/{id}`](https://openemail.uk/docs/api/reference/audiences#delete-audiences-id); SDK [`audiences.delete()`](https://openemail.uk/docs/sdk/reference/audiences#delete). ### `openemail audiences empty` Take every contact out of an audience and keep the audience ```bash openemail audiences empty [flags] ``` Removes every membership of the audience in one transaction and resolves with the audience as it now stands, `contactCount` 0, plus `removed`, the number of contacts taken out. The audience keeps its id, name and description, so anything that points at it still works. The contacts are not touched: each one stays in the address book, in the default audience and in every other audience it is in. The default audience cannot be emptied. The call is refused with 409 `audience_immutable` on `id`, because that audience holds every contact for as long as it is a contact. There is no undo. The app asks the person to confirm before it empties a list, but this call asks nothing: it needs no verification code, whether it is made with an API key or with the OAuth access token of an app the person connected. Check the id before you call it. - Scopes: `audiences:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): Audience id such as `aud_9f2c4b7e1a0d63d84c5f2e7b`. Not the default audience. **Examples** ```bash openemail audiences empty aud_9f2c4b7e1a0d63d84c5f2e7b ``` Skip the confirmation, for scripts ```bash openemail audiences empty aud_9f2c4b7e1a0d63d84c5f2e7b --yes ``` Also available in: API [`POST /audiences/{id}/empty`](https://openemail.uk/docs/api/reference/audiences#post-audiences-id-empty); SDK [`audiences.empty()`](https://openemail.uk/docs/sdk/reference/audiences#empty). ### `openemail audiences list-contacts` List one page of the contacts in one audience ```bash openemail audiences list-contacts [flags] ``` Returns one page of the contacts in the audience. The rows are the contacts themselves, not membership records, so they carry `email`, `name`, `source`, `notes`, `lastSeenAt`, `createdAt` and `updatedAt`, plus `addedAt`, the date the contact joined this audience, and `unsubscribedAt`, when it unsubscribed from a broadcast sent to this audience, or null while it is subscribed. An unsubscribed contact stays in the audience and broadcasts to it skip it. By default the order is the one `contacts.list` uses: the contacts most recently written to first, and those never written to last. `sort` picks another order, `q` searches names and addresses, `source` keeps only contacts saved by hand or only those recorded from the composer, and `statuses` keeps only the subscribed or only the unsubscribed. These are the controls on the audience page in the app. Paging is keyset: `--limit` takes 1 to 200 and defaults to 50, and `nextCursor` goes back as `--cursor` while `hasMore` is true, so every contact in the audience is reachable however large it grows. Send the same `q`, `source`, `sort` and `statuses` with every page. Reading the default audience here returns the whole address book. 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: `audiences:read`. - Needs a sign-in. **Arguments** - `` (required): Audience id such as `aud_9f2c4b7e1a0d63d84c5f2e7b`. **Flags** - `--limit ` (default `50`): Rows per page, a whole number from 1 to 200. The server defaults to 50. - `--cursor `: The `nextCursor` from the previous page. Never build one yourself; one that names no contact in this audience is a 400 `invalid_cursor`. - `--q `: Narrows to contacts whose name or address matches, up to 200 characters. When nothing matches exactly the search allows for a typo instead. - `--source `: Narrows to contacts recorded that way: `manual` for one somebody saved, `auto` for one recorded by a send from the app composer. - `--sort ` (default `"last-heard-newest"`): How the page is ordered. `last-heard-newest`, the default, puts the contacts most recently written to first and those never written to last, `last-heard-oldest` reverses it, `added-newest` and `added-oldest` order by `addedAt`, and `name` is alphabetical without case, with a contact that has no name sorting by its address. - `--statuses ` (repeatable): Keeps only `subscribed` members, only `unsubscribed` ones, or both. Leave it out, or name both, for everyone in the audience. `AUDIENCE_MEMBER_STATUSES` holds the values. - `--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 audiences list-contacts aud_9f2c4b7e1a0d63d84c5f2e7b ``` With optional flags ```bash openemail audiences list-contacts aud_9f2c4b7e1a0d63d84c5f2e7b --limit 200 --sort added-newest ``` Walk every page and stop after 100 items ```bash openemail audiences list-contacts aud_9f2c4b7e1a0d63d84c5f2e7b --all --max 100 ``` One JSON object per line when piped ```bash openemail audiences list-contacts aud_9f2c4b7e1a0d63d84c5f2e7b --all > audiences.ndjson ``` Also available in: API [`GET /audiences/{id}/contacts`](https://openemail.uk/docs/api/reference/audiences#get-audiences-id-contacts); SDK [`audiences.listContacts()`](https://openemail.uk/docs/sdk/reference/audiences#listContacts). ### `openemail audiences add-contact` Put a contact in an audience ```bash openemail audiences add-contact --email [flags] openemail audiences add-contact --data [flags] ``` Adds one contact to one audience and returns the membership, with the contact it points at. The address is trimmed and lower cased before the lookup, and it has to be a contact in this workspace already: an address that is not in the book is refused with 422 `contact_not_found` on `email`. Save it with `contacts.create` first. There is one membership per audience and contact, so adding somebody who is already in the audience returns the membership that is there, with its original `addedAt`, rather than adding a second one or failing. That makes the call safe to replay, and the SDK retries it after a network failure. Adding to the default audience is accepted and changes nothing, since every contact is already in it. - Scopes: `audiences:write`. - Needs a sign-in. **Arguments** - `` (required): Audience id such as `aud_9f2c4b7e1a0d63d84c5f2e7b`. **Flags** - `--email `: The address of a contact already in the workspace book, matched case insensitively. 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 audiences add-contact aud_9f2c4b7e1a0d63d84c5f2e7b --email grace@example.com ``` Read the whole body from a JSON file ```bash openemail audiences add-contact aud_9f2c4b7e1a0d63d84c5f2e7b --data @audience.json ``` Also available in: API [`POST /audiences/{id}/contacts`](https://openemail.uk/docs/api/reference/audiences#post-audiences-id-contacts); SDK [`audiences.addContact()`](https://openemail.uk/docs/sdk/reference/audiences#addContact). ### `openemail audiences remove-contact` Take a contact out of an audience ```bash openemail audiences remove-contact [flags] ``` Drops one membership and leaves everything else alone. The contact stays in the address book, in the default audience and in every other audience it was in. The address is trimmed and lower cased, and the SDK URL encodes it for the path. A contact that is not in this audience is a 404, so a typo cannot report a removal that never happened. The default audience cannot be thinned. Removing a contact from it is refused with 409 `audience_immutable`, because it holds every contact by definition. Use `contacts.delete` when you mean the contact to go. - Scopes: `audiences:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): Audience id such as `aud_9f2c4b7e1a0d63d84c5f2e7b`. Not the default audience. - `` (required): The contact's address, matched case insensitively. **Examples** ```bash openemail audiences remove-contact aud_9f2c4b7e1a0d63d84c5f2e7b grace@example.com ``` Skip the confirmation, for scripts ```bash openemail audiences remove-contact aud_9f2c4b7e1a0d63d84c5f2e7b grace@example.com --yes ``` Also available in: API [`DELETE /audiences/{id}/contacts/{email}`](https://openemail.uk/docs/api/reference/audiences#delete-audiences-id-contacts-email); SDK [`audiences.removeContact()`](https://openemail.uk/docs/sdk/reference/audiences#removeContact). ### `openemail audiences add-contacts` Put up to 200 existing contacts in an audience in one call ```bash openemail audiences add-contacts --emails [flags] openemail audiences add-contacts --data [flags] ``` Adds many contacts to one audience in one transaction and reports what happened to each address. Each address is trimmed and lower cased, a repeat counts once, and each has to be a contact in this workspace already. Nothing is refused for one address. An address that is not a contact is returned in `missing` and the others are still added, and a contact that is in the audience already is counted in `unchanged` and keeps its original `addedAt`. `added` counts the contacts that joined in this call. This never creates a contact. To save new addresses and put them in the audience in the same call, use `importContacts`. Adding to the default audience succeeds with `added: 0`, since every contact is already in it. - Scopes: `audiences:write`. - Needs a sign-in. **Arguments** - `` (required): Audience id such as `aud_9f2c4b7e1a0d63d84c5f2e7b`. **Flags** - `--emails ` (repeatable): From 1 to 200 addresses of contacts already in the workspace book, matched case insensitively. An empty array or more than 200 is a 422 `invalid_parameter` on `emails`, and an empty or overlong address is the same error on that entry, such as `emails.2`. 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 audiences add-contacts aud_9f2c4b7e1a0d63d84c5f2e7b --emails grace@example.com,ada@example.com,nobody@example.com ``` Read the whole body from a JSON file ```bash openemail audiences add-contacts aud_9f2c4b7e1a0d63d84c5f2e7b --data @audience.json ``` Also available in: API [`POST /audiences/{id}/contacts/batch`](https://openemail.uk/docs/api/reference/audiences#post-audiences-id-contacts-batch); SDK [`audiences.addContacts()`](https://openemail.uk/docs/sdk/reference/audiences#addContacts). ### `openemail audiences remove-contacts` Take up to 200 contacts out of an audience in one call ```bash openemail audiences remove-contacts --emails [flags] openemail audiences remove-contacts --data [flags] ``` Removes many contacts from one audience in one transaction and reports what happened to each address. Each address is trimmed and lower cased and a repeat counts once. The contacts stay in the address book, in the default audience and in every other audience they are in. Nothing is refused for one address, which is where this differs from `removeContact`. A contact that is not in this audience is returned in `notInAudience`, an address that is not a contact at all in `missing`, and the rest are still removed. `removed` counts the contacts taken out in this call. The default audience cannot be thinned. The call is refused with 409 `audience_immutable` on `id`, because that audience holds every contact by definition. Use `contacts.delete` when you mean a contact to go. - Scopes: `audiences:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): Audience id such as `aud_9f2c4b7e1a0d63d84c5f2e7b`. Not the default audience. **Flags** - `--emails ` (repeatable): From 1 to 200 addresses, matched case insensitively. An empty array or more than 200 is a 422 `invalid_parameter` on `emails`, and an empty or overlong address is the same error on that entry, such as `emails.2`. 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 audiences remove-contacts aud_9f2c4b7e1a0d63d84c5f2e7b --emails grace@example.com,ada@example.com ``` Read the whole body from a JSON file ```bash openemail audiences remove-contacts aud_9f2c4b7e1a0d63d84c5f2e7b --data @audience.json ``` Skip the confirmation, for scripts ```bash openemail audiences remove-contacts aud_9f2c4b7e1a0d63d84c5f2e7b --emails grace@example.com,ada@example.com --yes ``` Also available in: API [`POST /audiences/{id}/contacts/batch-remove`](https://openemail.uk/docs/api/reference/audiences#post-audiences-id-contacts-batch-remove); SDK [`audiences.removeContacts()`](https://openemail.uk/docs/sdk/reference/audiences#removeContacts). ### `openemail audiences import-contacts` Import up to 500 addresses into an audience, creating contacts as needed ```bash openemail audiences import-contacts --contacts [flags] openemail audiences import-contacts --data [flags] ``` Does what the CSV import on an audience page does, without the file. Each row is an address and an optional name, and the whole call runs in one transaction. An address that is not a contact yet is saved as one, with `source` set to `manual`, and joins the default audience as every new contact does. An address that is a contact already is reused as it stands: its name is kept, and a name sent here only fills one that is empty. Every imported contact ends up in this audience. Importing an address whose contact was deleted brings it back. A row whose address is not well formed is skipped rather than failing the call. It is counted in `skipped` and its address is returned in `invalid` exactly as you sent it, and every other row is still imported. Rows with the same address count once. - Scopes: `audiences:write`, `contacts:write`. - Needs a sign-in. **Arguments** - `` (required): Audience id such as `aud_9f2c4b7e1a0d63d84c5f2e7b`. The default audience is accepted and saves the contacts without putting them in any other list. **Flags** - `--contacts `: From 1 to 500 rows, each `{ email, name }`. `email` is required, at most 320 characters, and trimmed and lower cased. `name` is optional, at most 200 characters, and used for a new contact or for an existing one whose name is empty. An empty array, more than 500 rows, an empty `email` or any other key in a row is a 422. JSON shaped as `Array`, inline or from a file with @path. 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 audiences import-contacts aud_9f2c4b7e1a0d63d84c5f2e7b --contacts @contacts.json ``` Read the whole body from a JSON file ```bash openemail audiences import-contacts aud_9f2c4b7e1a0d63d84c5f2e7b --data @audience.json ``` Also available in: API [`POST /audiences/{id}/import`](https://openemail.uk/docs/api/reference/audiences#post-audiences-id-import); SDK [`audiences.importContacts()`](https://openemail.uk/docs/sdk/reference/audiences#importContacts).