--- title: "nextmail suppressions" description: "Every command in this namespace, with its arguments, flags and examples." url: "https://nextmail.sh/docs/cli/reference/suppressions" area: "CLI" category: "Reference" --- # nextmail suppressions Every command in this namespace, with its arguments, flags and examples. ## Commands ### `nextmail suppressions list` List one page of the suppression list ```bash nextmail suppressions list [flags] ``` Resolves one page of the addresses this workspace will not send to, newest first: every address that bounced hard, complained, or was added by hand. A send to a suppressed address is refused for that recipient before anything leaves, and a message whose recipients are all suppressed fails outright. The list belongs to the whole workspace, so a key limited to some addresses reads all of it, and a row names the recipient, never which of your addresses sent to it. `removable` says whether `remove` will take the address off. A hard bounce is permanent here, because the address could not take mail. A complaint or a manual entry can be removed. 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: `settings:read`. - Needs a sign-in. - Aliases: `ls`. **Flags** - `--q `: Searches the address, the reason and the detail. Words match loosely, and a close spelling is tried when nothing matches exactly. - `--reason `: Keeps one kind: `bounce`, `complaint` or `manual`. - `--limit ` (default `25`): Page size, from 1 to 100. The server defaults to 25. - `--cursor `: The `nextCursor` of the previous page. Leave it out for the first page. - `--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 nextmail suppressions list ``` With optional flags ```bash nextmail suppressions list --reason complaint ``` Walk every page and stop after 100 items ```bash nextmail suppressions list --all --max 100 ``` One JSON object per line when piped ```bash nextmail suppressions list --all > suppressions.ndjson ``` Also available in: API [`GET /suppressions`](https://nextmail.sh/docs/api/reference/suppressions#get-suppressions); TypeScript [`nextmail.suppressions.list()`](https://nextmail.sh/docs/sdk/reference/suppressions#list); Python [`suppressions.list()`](https://nextmail.sh/docs/python/reference/suppressions#list); Ruby [`suppressions.list`](https://nextmail.sh/docs/ruby/reference/suppressions#list); PHP [`suppressions->list`](https://nextmail.sh/docs/php/reference/suppressions#list); Go [`Suppressions.List`](https://nextmail.sh/docs/go/reference/suppressions#list); Java [`suppressions().list`](https://nextmail.sh/docs/java/reference/suppressions#list); C# [`Suppressions.ListAsync`](https://nextmail.sh/docs/csharp/reference/suppressions#list). ### `nextmail suppressions get` Read one suppressed address by id ```bash nextmail suppressions get [flags] ``` Resolves one row of the suppression list: the address, why it is there, the detail the bounce or complaint carried, whether it can be removed and when it was added. - Scopes: `settings:read`. - Needs a sign-in. - Aliases: `show`, `view`. **Arguments** - `` (required): The id from `list`. **Examples** ```bash nextmail suppressions get 7b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e ``` Print the raw JSON ```bash nextmail suppressions get 7b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e --json ``` Also available in: API [`GET /suppressions/{id}`](https://nextmail.sh/docs/api/reference/suppressions#get-suppressions-id); TypeScript [`nextmail.suppressions.get()`](https://nextmail.sh/docs/sdk/reference/suppressions#get); Python [`suppressions.get()`](https://nextmail.sh/docs/python/reference/suppressions#get); Ruby [`suppressions.get`](https://nextmail.sh/docs/ruby/reference/suppressions#get); PHP [`suppressions->get`](https://nextmail.sh/docs/php/reference/suppressions#get); Go [`Suppressions.Get`](https://nextmail.sh/docs/go/reference/suppressions#get); Java [`suppressions().get`](https://nextmail.sh/docs/java/reference/suppressions#get); C# [`Suppressions.GetAsync`](https://nextmail.sh/docs/csharp/reference/suppressions#get). ### `nextmail suppressions add` Stop sending to an address ```bash nextmail suppressions add --email [flags] nextmail suppressions add --data [flags] ``` Puts an address on the suppression list by hand, with `reason: 'manual'`, so no address in the workspace sends to it again until it is removed. It is the Block an address control on the Blocked addresses screen. Adding an address that is already there changes nothing: the server answers 200 with the row it already holds, whatever its reason, where a new entry answers 201. Either way you get the row back. A new entry fires `suppression.added` to the webhooks that asked for it. - Scopes: `settings:write`. - Needs a sign-in. - Aliases: `new`, `create`. **Flags** - `--email `: The address to stop sending to. It is trimmed and lower cased. 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 nextmail suppressions add --email noreply@example.com ``` Read the whole body from a JSON file ```bash nextmail suppressions add --data @suppression.json ``` Also available in: API [`POST /suppressions`](https://nextmail.sh/docs/api/reference/suppressions#post-suppressions); TypeScript [`nextmail.suppressions.add()`](https://nextmail.sh/docs/sdk/reference/suppressions#add); Python [`suppressions.add()`](https://nextmail.sh/docs/python/reference/suppressions#add); Ruby [`suppressions.add`](https://nextmail.sh/docs/ruby/reference/suppressions#add); PHP [`suppressions->add`](https://nextmail.sh/docs/php/reference/suppressions#add); Go [`Suppressions.Add`](https://nextmail.sh/docs/go/reference/suppressions#add); Java [`suppressions().add`](https://nextmail.sh/docs/java/reference/suppressions#add); C# [`Suppressions.AddAsync`](https://nextmail.sh/docs/csharp/reference/suppressions#add). ### `nextmail suppressions remove` Allow mail to an address again ```bash nextmail suppressions remove [flags] ``` Takes an address off the suppression list, so mail may go to it again. It is Allow again on the Blocked addresses screen, and it fires `suppression.removed`. Only a complaint or a manual entry can be removed. A hard bounce answers 409 `suppression_not_removable` and stays, because the address could not take mail: check it is spelled right and send to the corrected one instead. - Scopes: `settings:write`. - Needs a sign-in. - Asks you to confirm. - Aliases: `rm`, `del`, `delete`. **Arguments** - `` (required): The id from `list`. **Examples** ```bash nextmail suppressions remove 7b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e ``` Skip the confirmation, for scripts ```bash nextmail suppressions remove 7b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e --yes ``` Also available in: API [`DELETE /suppressions/{id}`](https://nextmail.sh/docs/api/reference/suppressions#delete-suppressions-id); TypeScript [`nextmail.suppressions.remove()`](https://nextmail.sh/docs/sdk/reference/suppressions#remove); Python [`suppressions.remove()`](https://nextmail.sh/docs/python/reference/suppressions#remove); Ruby [`suppressions.remove`](https://nextmail.sh/docs/ruby/reference/suppressions#remove); PHP [`suppressions->remove`](https://nextmail.sh/docs/php/reference/suppressions#remove); Go [`Suppressions.Remove`](https://nextmail.sh/docs/go/reference/suppressions#remove); Java [`suppressions().remove`](https://nextmail.sh/docs/java/reference/suppressions#remove); C# [`Suppressions.RemoveAsync`](https://nextmail.sh/docs/csharp/reference/suppressions#remove). ### `nextmail suppressions list-unsubscribes` List one page of the people who unsubscribed ```bash nextmail suppressions list-unsubscribes [flags] ``` Resolves one page of the people who asked this workspace for no more marketing mail, newest first. It is the Unsubscribed list on the Blocked addresses screen in Settings. An unsubscribe belongs to the whole workspace and outlasts the contact: removing the person from an audience, deleting the contact or importing the address again never brings them back. Every broadcast and automation email skips them, and adding them to an audience records them there as unsubscribed. Mail people write to you, and your replies, still reach them, because only marketing mail stops. `list` is the hard block on every kind of mail. `removable` says whether `removeUnsubscribe` takes it back, which is true only for one the team recorded by hand. A person who unsubscribed decides alone whether to come back: through a sign-up form they confirm from their inbox, or Subscribe again on the unsubscribe page. - Scopes: `settings:read`. - Needs a sign-in. **Flags** - `--q `: One whole address, matched exactly and without regard to case. The addresses are stored encrypted, so a part of one finds nothing. - `--source `: Keeps one way of unsubscribing: `link`, `one_click`, `complaint`, `import` or `manual`. - `--limit ` (default `25`): Page size, from 1 to 100. The server defaults to 25. - `--cursor `: The `nextCursor` of the previous page. Leave it out for the first page. **Examples** ```bash nextmail suppressions list-unsubscribes ``` With optional flags ```bash nextmail suppressions list-unsubscribes --q ada@example.com --source one_click ``` Also available in: API [`GET /suppressions/unsubscribes`](https://nextmail.sh/docs/api/reference/suppressions#get-suppressions-unsubscribes); TypeScript [`nextmail.suppressions.listUnsubscribes()`](https://nextmail.sh/docs/sdk/reference/suppressions#listUnsubscribes); Python [`suppressions.list_unsubscribes()`](https://nextmail.sh/docs/python/reference/suppressions#listUnsubscribes); Ruby [`suppressions.list_unsubscribes`](https://nextmail.sh/docs/ruby/reference/suppressions#listUnsubscribes); PHP [`suppressions->listUnsubscribes`](https://nextmail.sh/docs/php/reference/suppressions#listUnsubscribes); Go [`Suppressions.ListUnsubscribes`](https://nextmail.sh/docs/go/reference/suppressions#listUnsubscribes); Java [`suppressions().listUnsubscribes`](https://nextmail.sh/docs/java/reference/suppressions#listUnsubscribes); C# [`Suppressions.ListUnsubscribesAsync`](https://nextmail.sh/docs/csharp/reference/suppressions#listUnsubscribes). ### `nextmail suppressions add-unsubscribe` Record that somebody unsubscribed ```bash nextmail suppressions add-unsubscribe --email [flags] nextmail suppressions add-unsubscribe --data [flags] ``` Records that somebody asked to stop getting marketing mail, for when they asked by phone, in a reply or anywhere else, with `source: 'manual'`. Their contact, if there is one, is unsubscribed from every audience at once, the automations sending to them end, and `contact.unsubscribed` fires. No broadcast or automation email goes to the address from then on, while ordinary mail and replies still do. Recording an address that is already on the list changes nothing: the server answers 200 with the record it holds, where a new one answers 201. - Scopes: `settings:write`. - Needs a sign-in. **Flags** - `--email `: The address that asked for no more marketing mail. It is trimmed and lower cased. 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 nextmail suppressions add-unsubscribe --email ada@example.com ``` Read the whole body from a JSON file ```bash nextmail suppressions add-unsubscribe --data @suppression.json ``` Also available in: API [`POST /suppressions/unsubscribes`](https://nextmail.sh/docs/api/reference/suppressions#post-suppressions-unsubscribes); TypeScript [`nextmail.suppressions.addUnsubscribe()`](https://nextmail.sh/docs/sdk/reference/suppressions#addUnsubscribe); Python [`suppressions.add_unsubscribe()`](https://nextmail.sh/docs/python/reference/suppressions#addUnsubscribe); Ruby [`suppressions.add_unsubscribe`](https://nextmail.sh/docs/ruby/reference/suppressions#addUnsubscribe); PHP [`suppressions->addUnsubscribe`](https://nextmail.sh/docs/php/reference/suppressions#addUnsubscribe); Go [`Suppressions.AddUnsubscribe`](https://nextmail.sh/docs/go/reference/suppressions#addUnsubscribe); Java [`suppressions().addUnsubscribe`](https://nextmail.sh/docs/java/reference/suppressions#addUnsubscribe); C# [`Suppressions.AddUnsubscribeAsync`](https://nextmail.sh/docs/csharp/reference/suppressions#addUnsubscribe). ### `nextmail suppressions remove-unsubscribe` Take back an unsubscribe the team recorded ```bash nextmail suppressions remove-unsubscribe [flags] ``` Takes back an unsubscribe the team recorded by hand, for one recorded by mistake. The audiences it unsubscribed are subscribed again, and `contact.resubscribed` fires. Every other kind is refused with 409 `unsubscribe_not_removable`, because a person who unsubscribed decides alone whether to come back: through a sign-up form they confirm from their inbox, or Subscribe again on the unsubscribe page. An address that has not unsubscribed is a 404. - Scopes: `settings:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): The address, as `listUnsubscribes` returns it. Case does not matter. **Examples** ```bash nextmail suppressions remove-unsubscribe ada@example.com ``` Skip the confirmation, for scripts ```bash nextmail suppressions remove-unsubscribe ada@example.com --yes ``` Also available in: API [`DELETE /suppressions/unsubscribes/{email}`](https://nextmail.sh/docs/api/reference/suppressions#delete-suppressions-unsubscribes-email); TypeScript [`nextmail.suppressions.removeUnsubscribe()`](https://nextmail.sh/docs/sdk/reference/suppressions#removeUnsubscribe); Python [`suppressions.remove_unsubscribe()`](https://nextmail.sh/docs/python/reference/suppressions#removeUnsubscribe); Ruby [`suppressions.remove_unsubscribe`](https://nextmail.sh/docs/ruby/reference/suppressions#removeUnsubscribe); PHP [`suppressions->removeUnsubscribe`](https://nextmail.sh/docs/php/reference/suppressions#removeUnsubscribe); Go [`Suppressions.RemoveUnsubscribe`](https://nextmail.sh/docs/go/reference/suppressions#removeUnsubscribe); Java [`suppressions().removeUnsubscribe`](https://nextmail.sh/docs/java/reference/suppressions#removeUnsubscribe); C# [`Suppressions.RemoveUnsubscribeAsync`](https://nextmail.sh/docs/csharp/reference/suppressions#removeUnsubscribe).