---
title: "suppressions"
description: "Addresses we will not send to. The `machinemail suppressions` commands: arguments, flags, examples and the API routes they call."
canonical: "https://machinemail.dev/docs/cli/commands/suppressions"
---

# suppressions

> Addresses we will not send to. The `machinemail suppressions` commands: arguments, flags, examples and the API routes they call.

Source: https://machinemail.dev/docs/cli/commands/suppressions

Addresses we will not send to. Also spelled `suppression`.

| Command                                       | Summary            |
| --------------------------------------------- | ------------------ |
| [`suppressions create`](#suppressions-create) | Add suppression    |
| [`suppressions delete`](#suppressions-delete) | Remove suppression |
| [`suppressions get`](#suppressions-get)       | Get suppression    |
| [`suppressions list`](#suppressions-list)     | List suppressions  |

Every command also takes the [global flags](https://machinemail.dev/docs/cli/commands#global-flags).

## suppressions create

Add suppression.

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.

Requires the list\_entry\_create permission.

```bash
machinemail suppressions create [flags]
```

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--idempotency-key <value>` | `string` |  | Makes the request safe to retry: a retry with the same key within 24 hours gets the first response back (with Idempotent-Replayed: true) instead of running again. 1 to 255 printable ASCII characters, a new value (a UUID) for each request. See https://machinemail.dev/docs/reference#idempotency. |
| `--email <value>` | `string` |  | Address to suppress. |
| `--detail <value>` | `string` |  | Note stored as --detail. |
| `--reason <value>` | `string` |  | Old name of --detail (it is stored as --detail; the suppression --reason is always manual). Ignored when --detail is set. |
| `-d, --data <json|@file|->` | `string` |  | Request body as JSON, @file or - for stdin; field flags override its keys. |

#### Examples

```bash
machinemail suppressions create --email someone@example.com
machinemail suppressions create --data @body.json
```

#### API

- [`POST /v0/suppressions`](https://machinemail.dev/docs/reference/api/suppressions#add-suppression)

## suppressions delete

Remove suppression.

Also: `machinemail suppressions rm`.

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](mailto:support@machinemail.dev)).

Requires the list\_entry\_delete permission.

```bash
machinemail suppressions delete <email> [flags]
```

#### Arguments

| Field | Type | | Description |
| --- | --- | --- | --- |
| `<email>` | `string` | required | The suppressed address (URL-encoded). |

#### Examples

```bash
machinemail suppressions delete someone@example.com
```

#### API

- [`DELETE /v0/suppressions/{email}`](https://machinemail.dev/docs/reference/api/suppressions#remove-suppression)

## suppressions get

Get suppression.

Requires the list\_entry\_read permission.

```bash
machinemail suppressions get <email> [flags]
```

#### Arguments

| Field | Type | | Description |
| --- | --- | --- | --- |
| `<email>` | `string` | required | The suppressed address (URL-encoded). |

#### Examples

```bash
machinemail suppressions get someone@example.com
```

#### API

- [`GET /v0/suppressions/{email}`](https://machinemail.dev/docs/reference/api/suppressions#get-suppression)

## suppressions list

List suppressions.

Also: `machinemail suppressions ls`.

Every suppressed address in the organization (also for pod and inbox credentials). Addresses are added automatically on permanent bounces and complaints.

Requires the list\_entry\_read permission.

```bash
machinemail suppressions list [flags]
```

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--limit <n>` | `integer` |  | Maximum number of items to return. Default 50, maximum 500; larger values are capped. Default: `50`. |
| `--page-token <value>` | `string` |  | next_page_token from the previous page. |
| `--ascending` | `boolean` |  | Sort oldest first. |
| `--all` | `boolean` |  | Follow next_page_token and return every page. |

#### Examples

```bash
machinemail suppressions list
machinemail suppressions list --all --json | jq '.suppressions | length'
```

#### API

- [`GET /v0/suppressions`](https://machinemail.dev/docs/reference/api/suppressions#list-suppressions)