| Method | Path | Summary |
| --- | --- | --- |
| `GET` | `/v0/suppressions` | [List Suppressions](/content/docs/reference/api/suppressions#list-suppressions/index.html) |
| `POST` | `/v0/suppressions` | [Add Suppression](/content/docs/reference/api/suppressions#add-suppression/index.html) |
| `GET` | `/v0/suppressions/{email}` | [Get Suppression](/content/docs/reference/api/suppressions#get-suppression/index.html) |
| `DELETE` | `/v0/suppressions/{email}` | [Remove Suppression](/content/docs/reference/api/suppressions#remove-suppression/index.html) |

## [List Suppressions](/content/docs/reference/api/suppressions#list-suppressions/index.html)

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 <api key>` or the dashboard `mm_session` cookie. Permission: `list_entry_read`.

#### [Query parameters](/content/docs/reference/api/suppressions#query-parameters/index.html)

FieldDescription

`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](/content/docs/reference/api/suppressions#response/index.html)

**200** A page of suppressions (`application/json`)

FieldDescription

`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\\[]](/content/docs/reference/api/objects#suppression/index.html) Required

Newest first unless ascending is set.

Each item of `suppressions` is a [Suppression](/content/docs/reference/api/objects#suppression/index.html):

FieldDescription

`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](/content/docs/reference/api/suppressions#errors/index.html)

| 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](/content/docs/reference/api/suppressions#example/index.html)

Request

```
curl "https://api.machinemail.dev/v0/suppressions" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

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](/content/docs/reference/api/suppressions#add-suppression/index.html)

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 <api key>` or the dashboard `mm_session` cookie. Permission: `list_entry_create`.

#### [Request body](/content/docs/reference/api/suppressions#request-body/index.html)

Content type: `application/json`.

FieldDescription

`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](/content/docs/reference/api/suppressions#response-1/index.html)

**201** Created (`application/json`)

FieldDescription

`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](/content/docs/reference/api/suppressions#errors-1/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/suppressions#example-1/index.html)

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"
}'
```

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](/content/docs/reference/api/suppressions#get-suppression/index.html)

http

```
GET /v0/suppressions/{email}
```

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `list_entry_read`.

#### [Path parameters](/content/docs/reference/api/suppressions#path-parameters/index.html)

FieldDescription

`email``string`Required

The suppressed address (URL-encoded).

#### [Response](/content/docs/reference/api/suppressions#response-2/index.html)

**200** The suppression (`application/json`)

FieldDescription

`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](/content/docs/reference/api/suppressions#errors-2/index.html)

| 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](/content/docs/reference/api/suppressions#example-2/index.html)

Request

```
curl "https://api.machinemail.dev/v0/suppressions/customer@example.com" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

## [Remove Suppression](/content/docs/reference/api/suppressions#remove-suppression/index.html)

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 <api key>` or the dashboard `mm_session` cookie. Permission: `list_entry_delete`.

#### [Path parameters](/content/docs/reference/api/suppressions#path-parameters-1/index.html)

FieldDescription

`email``string`Required

The suppressed address (URL-encoded).

#### [Response](/content/docs/reference/api/suppressions#response-3/index.html)

**200** Deleted (`application/json`)

FieldDescription

`ok``true`Required

#### [Errors](/content/docs/reference/api/suppressions#errors-3/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/suppressions#example-3/index.html)

Request

```
curl -X DELETE "https://api.machinemail.dev/v0/suppressions/customer@example.com" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "ok": true
}
```