--- title: "Suppressions" description: "Every operation in this group: what it accepts, what it returns and the errors it can answer with." url: "https://openemail.uk/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`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`suppressions.list()`](https://openemail.uk/docs/sdk/reference/suppressions#list), [`suppressions.listAll()`](https://openemail.uk/docs/sdk/reference/suppressions#listAll), [`suppressions.iterate()`](https://openemail.uk/docs/sdk/reference/suppressions#iterate); CLI [`openemail suppressions list`](https://openemail.uk/docs/cli/reference/suppressions#suppressions-list); MCP [`listSuppressions`](https://openemail.uk/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`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`suppressions.add()`](https://openemail.uk/docs/sdk/reference/suppressions#add); CLI [`openemail suppressions add`](https://openemail.uk/docs/cli/reference/suppressions#suppressions-add); MCP [`addSuppression`](https://openemail.uk/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`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`suppressions.get()`](https://openemail.uk/docs/sdk/reference/suppressions#get); CLI [`openemail suppressions get`](https://openemail.uk/docs/cli/reference/suppressions#suppressions-get); MCP [`listSuppressions`](https://openemail.uk/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`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`suppressions.remove()`](https://openemail.uk/docs/sdk/reference/suppressions#remove); CLI [`openemail suppressions remove`](https://openemail.uk/docs/cli/reference/suppressions#suppressions-remove); MCP [`removeSuppression`](https://openemail.uk/docs/mcp/tools/suppressions#removeSuppression). ### 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.