# Suppressions > List, add, check and remove the addresses MachineMail will not send to. Permanent bounces and complaints add an address to the suppression list automatically. Source: https://machinemail.dev/docs/reference/api/suppressions | Method | Path | Summary | | -------- | -------------------------- | ----------------------------------------- | | `GET` | `/v0/suppressions` | [List Suppressions](#list-suppressions) | | `POST` | `/v0/suppressions` | [Add Suppression](#add-suppression) | | `GET` | `/v0/suppressions/{email}` | [Get Suppression](#get-suppression) | | `DELETE` | `/v0/suppressions/{email}` | [Remove Suppression](#remove-suppression) | ## List Suppressions ```http GET /v0/suppressions ``` Every suppressed address in the organization (also for pod and inbox credentials). Addresses are added automatically on permanent bounces and complaints. **Authentication:** `Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `list_entry_read`. #### Query parameters | Field | Type | | Description | | --- | --- | --- | --- | | `limit` | `integer` | | Maximum number of items to return. Default 50, maximum 500; larger values are capped. | | `page_token` | `string` | | next_page_token from the previous page. | | `ascending` | `boolean` | | Sort oldest first. | #### Response **200** A page of suppressions (`application/json`) | Field | Type | | Description | | --- | --- | --- | --- | | `count` | `integer` | required | Number of items returned. | | `limit` | `integer` | | Maximum number of items per page. Default 50, maximum 500; larger values are capped. | | `next_page_token` | `string` | | Page token for pagination. Absent on the last page. | | `suppressions` | `Suppression[]` | required | Newest first unless ascending is set. | Each item of `suppressions` is a [Suppression](/content/docs/reference/api/objects#suppression/index.html): | Field | Type | | Description | | --- | --- | --- | --- | | `email` | `string` | required | The suppressed address (lowercased). | | `organization_id` | `string` | required | ID of the organization. | | `reason` | "bounce" \| "complaint" \| "manual" | required | bounce: a permanent bounce. complaint: the recipient reported spam; only MachineMail support can remove it. manual: added with POST /v0/suppressions. | | `detail` | `string` | | Free text: the bounce diagnostic, or the note given when the address was added manually. | | `source_message_id` | `string` | | Message whose bounce or complaint caused the suppression. | | `created_at` | `string (date-time)` | required | When the address was suppressed. | #### Errors | Status | Meaning | | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Invalid request: error.type is validation and error.param names the field. | | `401` | Missing, invalid, expired or revoked credential. | | `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register). | | `500` | Unexpected server error. | Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### Example ```bash title="Request" curl "https://api.machinemail.dev/v0/suppressions" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` ```json title="Response 200" { "count": 1, "limit": 50, "next_page_token": "eyJvIjo1MH0", "suppressions": [ { "email": "agent@machinemail.dev", "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e", "reason": "bounce", "detail": "string", "source_message_id": "string", "created_at": "2026-10-01T12:00:00.000Z" } ] } ``` ## Add Suppression ```http POST /v0/suppressions ``` Suppress an address for the whole organization, with `reason: "manual"`. Adding an address that is already suppressed replaces a `bounce` or `manual` suppression (its `reason` becomes `manual`); a `complaint` suppression is returned unchanged. Sends to a suppressed address return `403`. **Authentication:** `Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `list_entry_create`. #### Request body Content type: `application/json`. | Field | Type | | Description | | --- | --- | --- | --- | | `email` | `string` | required | Address to suppress. | | `detail` | `string` | | Note stored as detail. | | `reason` | `string` | deprecated | Old name of detail (it is stored as detail; the suppression reason is always manual). Ignored when detail is set. | #### Response **201** Created (`application/json`) #### Errors Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### Example ```bash title="Request" curl -X POST "https://api.machinemail.dev/v0/suppressions" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "email": "agent@machinemail.dev", "reason": "string" }' ``` ```json title="Response 201" { "email": "agent@machinemail.dev", "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e", "reason": "bounce", "detail": "string", "source_message_id": "string", "created_at": "2026-10-01T12:00:00.000Z" } ``` ## Get Suppression ```http GET /v0/suppressions/{email} ``` **Authentication:** `Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `list_entry_read`. #### Path parameters | Field | Type | | Description | | --- | --- | --- | --- | | `email` | `string` | required | The suppressed address (URL-encoded). | #### Response **200** The suppression (`application/json`) #### Errors | Status | Meaning | | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401` | Missing, invalid, expired or revoked credential. | | `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register). | | `404` | Not found. Also returned for resources outside the credential scope. | | `500` | Unexpected server error. | Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### Example ```bash title="Request" curl "https://api.machinemail.dev/v0/suppressions/customer@example.com" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` ```json title="Response 200" { "email": "agent@machinemail.dev", "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e", "reason": "bounce", "detail": "string", "source_message_id": "string", "created_at": "2026-10-01T12:00:00.000Z" } ``` ## Remove Suppression ```http DELETE /v0/suppressions/{email} ``` Allow sending to the address again. Organization-scoped credentials only: pod and inbox credentials get `403`. Only `bounce` and `manual` suppressions can be removed: a `complaint` suppression returns `403` (`Complaint suppressions can only be removed by MachineMail support; email support@machinemail.dev`). **Authentication:** `Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `list_entry_delete`. #### Path parameters | Field | Type | | Description | | --- | --- | --- | --- | | `email` | `string` | required | The suppressed address (URL-encoded). | #### Response **200** Deleted (`application/json`) | Field | Type | | Description | | --- | --- | --- | --- | | `ok` | `true` | required | | #### Errors Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### Example ```bash title="Request" curl -X DELETE "https://api.machinemail.dev/v0/suppressions/customer@example.com" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` ```json title="Response 200" { "ok": true } ```