--- title: "Suppressions" description: "Every operation in this group: what it accepts, what it returns and the errors it can answer with." url: "https://nextmail.sh/docs/api/reference/suppressions" area: "API" category: "Reference" --- # Suppressions Every operation in this group: what it accepts, what it returns and the errors it can answer with. ## Operations The addresses this workspace will not send to: hard bounces and complaints, recorded as they happen, and any address somebody blocks by hand. A send to one is refused for that recipient before anything leaves. A hard bounce stays for good; a complaint or a manual entry can be removed. Reading needs `settings:read` and changing needs `settings:write`, the scopes the Blocked addresses screen in Settings is gated on. ### `GET /suppressions` List suppressed addresses The addresses this workspace will not send to, newest first: every address that bounced hard, complained, or was added by hand. It is the Blocked addresses screen in Settings. 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 particular addresses or domains reads all of it. A row names the recipient and never which of your addresses sent to it. Requires the `settings:read` scope. - Scopes: `settings:read`. **Query parameters** - `q` (`string`, up to 320 characters): Searches the address, the reason and the detail. Words match loosely, and a close spelling is tried when nothing matches exactly. - `reason` (`string`, one of `"bounce"`, `"complaint"`, `"manual"`): Keeps one kind. - `limit` (`integer`, at least 1, at most 100, default `25`): Rows per page, 1 to 100. - `cursor` (`string`): The previous page's `nextCursor`, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400 `invalid_cursor`. **Returns** - `200` `SuppressionList`: A page of the suppression list, newest first. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: TypeScript [`nextmail.suppressions.list()`](https://nextmail.sh/docs/sdk/reference/suppressions#list), [`nextmail.suppressions.listAll()`](https://nextmail.sh/docs/sdk/reference/suppressions#listAll), [`nextmail.suppressions.iterate()`](https://nextmail.sh/docs/sdk/reference/suppressions#iterate); Python [`suppressions.list()`](https://nextmail.sh/docs/python/reference/suppressions#list), [`suppressions.list_all()`](https://nextmail.sh/docs/python/reference/suppressions#listAll), [`suppressions.iterate()`](https://nextmail.sh/docs/python/reference/suppressions#iterate); Ruby [`suppressions.list`](https://nextmail.sh/docs/ruby/reference/suppressions#list), [`suppressions.list_all`](https://nextmail.sh/docs/ruby/reference/suppressions#listAll), [`suppressions.iterate`](https://nextmail.sh/docs/ruby/reference/suppressions#iterate); PHP [`suppressions->list`](https://nextmail.sh/docs/php/reference/suppressions#list), [`suppressions->listAll`](https://nextmail.sh/docs/php/reference/suppressions#listAll), [`suppressions->iterate`](https://nextmail.sh/docs/php/reference/suppressions#iterate); Go [`Suppressions.List`](https://nextmail.sh/docs/go/reference/suppressions#list), [`Suppressions.ListAll`](https://nextmail.sh/docs/go/reference/suppressions#listAll), [`Suppressions.Iterate`](https://nextmail.sh/docs/go/reference/suppressions#iterate); Java [`suppressions().list`](https://nextmail.sh/docs/java/reference/suppressions#list), [`suppressions().listAll`](https://nextmail.sh/docs/java/reference/suppressions#listAll), [`suppressions().iterate`](https://nextmail.sh/docs/java/reference/suppressions#iterate); C# [`Suppressions.ListAsync`](https://nextmail.sh/docs/csharp/reference/suppressions#list), [`Suppressions.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/suppressions#listAll), [`Suppressions.IterateAsync`](https://nextmail.sh/docs/csharp/reference/suppressions#iterate); CLI [`nextmail suppressions list`](https://nextmail.sh/docs/cli/reference/suppressions#suppressions-list); MCP [`listSuppressions`](https://nextmail.sh/docs/mcp/tools/suppressions#listSuppressions). ### `POST /suppressions` Add a suppressed address Puts an address on the list by hand, with `reason: "manual"`, so no address in the workspace sends to it until it is removed. Adding one that is already there changes nothing and answers 200 with the row it already holds, whatever its reason. A new entry fires `suppression.added`. The list stops mail from every address in the workspace, so a key limited to particular addresses or domains, and an app connected by anybody but the owner, cannot change it. Requires the `settings:write` scope. - Scopes: `settings:write`. **Request body** - `email` (`string`, required, up to 320 characters, format `email`): The address to stop sending to. Trimmed and lower-cased on the way in. **Returns** - `200` `Suppression`: It was already on the list. The row that was there, unchanged. - `201` `Suppression`: Added. Nothing is sent to the address from here on. **Errors** - `422`: `invalid_parameter` for an address that is not one, or `capability_unsupported` for a key limited to particular addresses or domains. - The errors every operation can return: `400`, `401`, `403`, `404`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: 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); CLI [`nextmail suppressions add`](https://nextmail.sh/docs/cli/reference/suppressions#suppressions-add); MCP [`addSuppression`](https://nextmail.sh/docs/mcp/tools/suppressions#addSuppression). ### `GET /suppressions/{id}` Retrieve a suppressed address One row of the suppression list. Requires the `settings:read` scope. - Scopes: `settings:read`. **Path parameters** - `id` (`string`, required): The id from `GET /suppressions`. **Returns** - `200` `Suppression`: The row. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: 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); CLI [`nextmail suppressions get`](https://nextmail.sh/docs/cli/reference/suppressions#suppressions-get); MCP [`listSuppressions`](https://nextmail.sh/docs/mcp/tools/suppressions#listSuppressions). ### `DELETE /suppressions/{id}` Remove a suppressed address Takes an address off the 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. Requires the `settings:write` scope. - Scopes: `settings:write`. **Path parameters** - `id` (`string`, required): The id from `GET /suppressions`. **Returns** - `200` `object`: Removed. Mail may go to the address again. - `object` (`string`, one of `"suppression"`) - `id` (`string`) - `email` (`string`) - `deleted` (`boolean`, one of `true`) **Errors** - `409`: `suppression_not_removable`: the address bounced hard, so it stays. Check the address is right and send to the corrected one. - `422`: `capability_unsupported` for a key limited to particular addresses or domains. - The errors every operation can return: `400`, `401`, `403`, `404`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: 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); CLI [`nextmail suppressions remove`](https://nextmail.sh/docs/cli/reference/suppressions#suppressions-remove); MCP [`removeSuppression`](https://nextmail.sh/docs/mcp/tools/suppressions#removeSuppression). ### `GET /suppressions/unsubscribes` List unsubscribes 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 the replies you send, still reach them, because only marketing mail stops. A hard block on every kind of mail is the suppression list, `GET /suppressions`. Somebody stops being on this list only by their own hand: a sign-up they confirm from their inbox, or Subscribe again on the unsubscribe page. An unsubscribe recorded by hand with `POST /suppressions/unsubscribes` is the one kind `DELETE` takes back. Requires the `settings:read` scope. - Scopes: `settings:read`. **Query parameters** - `q` (`string`, up to 320 characters): One whole address, matched exactly and without regard to case. Addresses here are stored encrypted, so a part of one finds nothing. - `source` (`string`, one of `"link"`, `"one_click"`, `"manual"`, `"complaint"`, `"import"`): Keeps one way of unsubscribing. - `limit` (`integer`, at least 1, at most 100, default `25`): Rows per page, 1 to 100. - `cursor` (`string`): The previous page's `nextCursor`, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400 `invalid_cursor`. **Returns** - `200` `UnsubscribeList`: A page of the unsubscribe list, newest first. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: 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); CLI [`nextmail suppressions list-unsubscribes`](https://nextmail.sh/docs/cli/reference/suppressions#suppressions-list-unsubscribes); MCP [`listUnsubscribes`](https://nextmail.sh/docs/mcp/tools/suppressions#listUnsubscribes). ### `POST /suppressions/unsubscribes` Record an unsubscribe 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. Recording an address that is already on the list changes nothing and answers 200. The list covers every address in the workspace, so a key limited to particular addresses or domains, and an app connected by anybody but the owner, cannot change it. Requires the `settings:write` scope. - Scopes: `settings:write`. **Request body** - `email` (`string`, required, up to 320 characters, format `email`): The address that asked for no more marketing mail. Trimmed and lower-cased on the way in. **Returns** - `200` `Unsubscribe`: The address had already unsubscribed. The record that was there. - `201` `Unsubscribe`: Recorded. No broadcast or automation email goes to the address from here on. **Errors** - `422`: `invalid_parameter` for an address that is not one, or `capability_unsupported` for a key limited to particular addresses or domains. - The errors every operation can return: `400`, `401`, `403`, `404`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: 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); CLI [`nextmail suppressions add-unsubscribe`](https://nextmail.sh/docs/cli/reference/suppressions#suppressions-add-unsubscribe); MCP [`addUnsubscribe`](https://nextmail.sh/docs/mcp/tools/suppressions#addUnsubscribe). ### `DELETE /suppressions/unsubscribes/{email}` Take back a recorded unsubscribe 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 source 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. Requires the `settings:write` scope. - Scopes: `settings:write`. **Path parameters** - `email` (`string`, required, up to 320 characters): The address that unsubscribed, URL-encoded. Case does not matter. **Returns** - `200` `object`: Taken back. The audiences it unsubscribed are subscribed again. - `object` (`string`, required, one of `"unsubscribe"`) - `email` (`string`, required) - `deleted` (`boolean`, required, one of `true`) **Errors** - `409`: `unsubscribe_not_removable`: the person unsubscribed themselves, complained, or left at another provider, so only they can subscribe again. - `422`: `capability_unsupported` for a key limited to particular addresses or domains. - The errors every operation can return: `400`, `401`, `403`, `404`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: 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); CLI [`nextmail suppressions remove-unsubscribe`](https://nextmail.sh/docs/cli/reference/suppressions#suppressions-remove-unsubscribe); MCP [`removeUnsubscribe`](https://nextmail.sh/docs/mcp/tools/suppressions#removeUnsubscribe). ### Objects #### `Suppression` `object` - `object` (`string`, one of `"suppression"`) - `id` (`string`) - `email` (`string`): The recipient address, lower-cased. It is somebody you sent to, not one of your own. - `reason` (`string`, one of `"bounce"`, `"complaint"`, `"manual"`): `bounce` is a hard bounce and stays for good. `complaint` means the recipient marked a message as spam. `manual` means somebody added it. - `detail` (`string`, nullable): What the bounce or complaint said, when it said anything. - `removable` (`boolean`): Whether `DELETE /suppressions/{id}` will take it off. False for a bounce. - `createdAt` (`string`, format `date-time`) #### `SuppressionList` `object` - `object` (`string`, one of `"list"`) - `data` (`Suppression[]`) - `hasMore` (`boolean`): True when another page follows. Pass `nextCursor` back as `cursor` to read it. - `nextCursor` (`string`, nullable): An opaque cursor for the next page, or null on the last page. Pass it back unchanged. #### `Unsubscribe` `object` - `object` (`string`, required, one of `"unsubscribe"`) - `email` (`string`, required): The address, lower-cased. - `source` (`string`, required, one of `"link"`, `"one_click"`, `"manual"`, `"complaint"`, `"import"`): `link` is the unsubscribe page, `one_click` the unsubscribe button a mail app shows from the List-Unsubscribe header, `complaint` a spam report, `import` an unsubscribe brought from another provider, and `manual` one the team recorded. - `broadcastId` (`string`, required, nullable): The broadcast whose link or header they used, when it was one. - `automationId` (`string`, required, nullable): The automation whose link or header they used, when it was one. - `removable` (`boolean`, required): Whether `DELETE /suppressions/unsubscribes/{email}` takes it back. True only for `manual`. - `createdAt` (`string`, required, format `date-time`): When they unsubscribed. #### `UnsubscribeList` `object` - `object` (`string`, one of `"list"`) - `data` (`Unsubscribe[]`) - `hasMore` (`boolean`): True when another page follows. Pass `nextCursor` back as `cursor` to read it. - `nextCursor` (`string`, nullable): An opaque cursor for the next page, or null on the last page. Pass it back unchanged.