Contacts, audiences and broadcasts

Four namespaces cover the people you write to. Contacts are the workspace address book, audiences are named lists of contacts, a broadcast sends one message to everybody in some audiences, and the suppression list holds the addresses the workspace will not send to. Each command calls one SDK method, so the SDK pages describe the same calls in more depth.

• —A contact has no id. Its address is the key every contacts command takes, trimmed and lower cased, so Grace@Example.com and grace@example.com are one contact. An audience has an aud_ id, a broadcast a brd_ id, and a suppression the id suppressions list prints.
• —Every contact is in the default audience for as long as it exists. That audience cannot be deleted, emptied or thinned, and builtin is default on it.
• —The address book belongs to the workspace, so every member and every key reads and writes the same one.
• —Each namespace also answers to its singular, as in nextmail contact get, and the usual aliases work: ls, show, new, edit and rm. In suppressions, whose verbs are add and remove, new leads to add and rm to remove.

The workspace address book: the people a member has written to from the app composer, plus anybody saved by hand. Mail that arrives adds nobody, and neither does a send through the API or the CLI.

Named lists of contacts, up to 100 in a workspace. An address has to be a contact before it joins one, except through import-contacts, which saves new addresses as it goes.

One message to everybody in up to 10 audiences, sent as a separate copy for each person, with the merge fields filled in and an unsubscribe link. Each copy is an ordinary email with its own msg_ id, events and webhooks.

The addresses this workspace will not send to: hard bounces and complaints, recorded as they happen, and any address you add by hand. A send to one is refused for that recipient before anything leaves.

Most commands need the read or write scope of their namespace. A few need another, because they read or change something else:

• —A key limited to particular addresses or domains reads and writes the same address book as every other key. It sees only the broadcasts sent from an address or domain it holds, gets the saved contacts alone from list-people, and is refused with 422 capability_unsupported by contacts list-threads, activity, block and unblock, and by suppressions add and remove.
• —A browser sign-in by a member who reaches only some addresses is refused with 422 capability_unsupported on every contacts, audiences and broadcasts command. suppressions add refuses a browser sign-in by anybody but the workspace owner.

Build an audience from a file, then count who a broadcast to it would reach. import-contacts saves the addresses that are not contacts yet, and running it again creates and adds nothing twice.

[  { "email": "ada@example.com", "name": "Ada Lovelace" },  { "email": "grace@example.com", "name": "Grace Hopper" },  { "email": "katherine@example.com" }]

AUDIENCE=$(nextmail audiences create --name 'Product updates' --json | jq -r .id)nextmail audiences import-contacts "$AUDIENCE" --contacts @contacts.jsonnextmail broadcasts preview --audience-ids "$AUDIENCE"

Check a broadcast with --dry-run, which prints the request and sends nothing, then send it. The broadcast is created at once and sent in the background, so poll get to follow it. This body does not place {{unsubscribeUrl}}, so every copy gets a one-line unsubscribe footer.

{  "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>",  "scheduledAt": "2026-10-01T09:00:00Z"}

nextmail broadcasts send --data @broadcast.json --dry-runBROADCAST=$(nextmail broadcasts send --data @broadcast.json --yes --json | jq -r .id)nextmail broadcasts get "$BROADCAST"nextmail broadcasts stats "$BROADCAST" --grain day

See who a broadcast did not reach. --ndjson prints one recipient per line, and --all --json one document with every page.

nextmail broadcasts list-recipients brd_5a8c1e3f7b2d94a06c8e1f3b --filter bounced --ndjson | jq -r .emailnextmail broadcasts list-recipients brd_5a8c1e3f7b2d94a06c8e1f3b --filter not_opened --all --json | jq ".items | length"nextmail suppressions list --reason bounce --all --max 50

Copy the subscribed members of one audience into another. jq turns the stream into the body add-contacts takes, and --data - reads it from stdin. --max 200 keeps it to the 200 addresses one call accepts.

nextmail audiences list-contacts aud_9f2c4b7e1a0d63d84c5f2e7b --statuses subscribed --max 200 --ndjson \  | jq -s '{ emails: map(.email) }' \  | nextmail audiences add-contacts aud_1c4e7a9b2d0f36e85a7c1b4d --data -

Delete every contact the composer recorded at one domain. delete-many takes up to 200 addresses a call, so xargs -n 200 splits a longer list. Check the batches with --dry-run first, because there is no undo.

nextmail contacts list --source auto --all --ndjson \  | jq -r 'select(.email | endswith("@old-vendor.example")) | .email' > leaving.txtxargs -n 200 nextmail contacts delete-many --dry-run < leaving.txtxargs -n 200 nextmail contacts delete-many --yes < leaving.txt

Stop sending to an address, allow one again, and block a sender. removable says which rows suppressions remove will take.

nextmail suppressions add --email noreply@example.comnextmail suppressions list --q ada@example.com --json | jq -r '.items[] | select(.removable) | .id'nextmail suppressions remove 7b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e --yesnextmail contacts block spammer@example.com

These commands ask you to confirm in a terminal before they run:

• —--yes confirms for you. Unattended, with --json or --no-input, in CI or without a terminal, a command that would ask stops with Refusing to run unattended. Pass --yes to confirm. and exit code 2.
• —--dry-run prints the request the command would send and exits with code 0, without asking and without changing anything.
• —With a browser sign-in, audiences delete asks for a verification code first, as the web app does. --yes never skips it, and unattended the command stops with exit code 4. Run nextmail verify beforehand, or use an API key, which is never asked.
• —audiences empty never asks for a verification code, so check the id before you pass --yes.

Every command that lists reads one page. When more remain, pass the cursor it printed to --cursor, with the same filters, or read them all:

• —--all reads every page and streams the items: a table on a terminal, and one JSON object per line when piped or with --ndjson.
• —--max <n> stops after that many items, and implies --all.
• —--json prints one { items, hasMore, nextCursor } document, --all included.
• —A malformed or stale cursor is a 400 invalid_cursor. Start again without one.

• —contacts create refuses an address already in the book with 409 contact_exists, so a retry never overwrites a name somebody edited. contacts save never refuses: it saves, keeps or brings back the address, whatever state it is in.
• —contacts delete also takes an address that was only ever seen in mail, which takes that person off list-people. The mail stays. There is no undo: saving the address again starts a contact with no name, no notes and no audience beyond the default one.
• —The address is the identity of a contact, so contacts update cannot change it. Moving a contact is a delete and a create.
• —contacts set-photo reads the image from a file, or from stdin with -. Pass --content-type, such as image/jpeg: without it the image can go as application/octet-stream, which the server refuses with 422 invalid_image.
• —broadcasts send --scheduled-at takes an ISO 8601 time such as 2026-10-01T09:00:00Z, or an ISO 8601 duration such as PT2H or P1D, up to 365 days out. The short delays send --at takes, such as 2h, are refused here.
• —Merge fields work in --subject, --html and --text: {{firstName}}, {{lastName}}, {{name}}, {{email}} and {{unsubscribeUrl}}, each with a fallback after a bar, as in {{firstName|there}}. A body that does not place {{unsubscribeUrl}} gets a one-line unsubscribe footer. A template is sent as it is, so put the link in the template.
• —A custom field of the contact is {{attributes.<key>}} in --subject, --html and --text, such as {{attributes.plan|Free}}.
• —A broadcast is checked against the monthly sends of the plan before anything is written, and each copy counts as one send. One the allowance cannot cover is refused with 429 send_quota_exceeded, and nothing is left behind.
• —Pass your own --idempotency-key to broadcasts send when a script may run the step again. The same key answers with the broadcast it created instead of sending a new one.
• —A contact who unsubscribes from a broadcast stays in the audience with unsubscribedAt set, and later broadcasts to that audience skip it. audiences list-contacts --statuses unsubscribed lists them.
• —A hard bounce stays on the suppression list. suppressions remove refuses it with 409 suppression_not_removable, and removable on each row says so in advance.