---
title: "nextmail.suppressions"
description: "Every method in this namespace: its signature, its parameters, what it returns and an example."
url: "https://nextmail.sh/docs/python/reference/suppressions"
area: "Python"
category: "Reference"
---

# nextmail.suppressions

Every method in this namespace: its signature, its parameters, what it returns and an example.

## Methods

The addresses this workspace will not send to: hard bounces, complaints and the ones you block by hand.

### `suppressions.list()`

List one page of the suppression list

```python
def list(
    *,
    limit: int | None = None,
    cursor: str | None = None,
    q: str | None = None,
    reason: SuppressionReason | None = None,
    api_key: str | None = None,
    timeout: float | None = None,
) -> Page[SuppressionResource]
```

Returns one page of the addresses this workspace will not send to, newest first: every address that bounced hard, complained, or was added by hand. `list_all` collects every page into one list and `iterate` walks them lazily.

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 some addresses reads all of it, and a row names the recipient, never which of your addresses sent to it.

`removable` says whether `remove` will take the address off. A hard bounce is permanent here, because the address could not take mail. A complaint or a manual entry can be removed.

Scopes: `settings:read`.

**Parameters**

- `limit` (`int`): Page size, from 1 to 100. The server defaults to 25.
- `cursor` (`str`): The `nextCursor` of the previous page. Leave it out for the first page.
- `q` (`str`): Searches the address, the reason and the detail. Words match loosely, and a close spelling is tried when nothing matches exactly.
- `reason` (`SuppressionReason`): Keeps one kind: `bounce`, `complaint` or `manual`.
- `api_key` (`str`): Overrides the client API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `NextmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`Page[SuppressionResource]`, a dict with `items`, `hasMore` and `nextCursor`. Each item has `id`, `email`, `reason`, `detail`, `removable` and `createdAt`.

**Example**

```python
from nextmail import nextmail

page = nextmail.suppressions.list(reason='complaint')

for row in page['items']:
    print(row['email'], row['createdAt'])
```

**Notes**

- Needs `settings:read`, the scope the Blocked addresses screen in Settings is gated on.
- The cursor is opaque and holds where the last row sat, so an address removed between pages never breaks the walk. A cursor this list did not hand out is a 400 `invalid_cursor`.

Also available in: API [`GET /suppressions`](https://nextmail.sh/docs/api/reference/suppressions#get-suppressions); TypeScript [`nextmail.suppressions.list()`](https://nextmail.sh/docs/sdk/reference/suppressions#list); Ruby [`suppressions.list`](https://nextmail.sh/docs/ruby/reference/suppressions#list); PHP [`suppressions->list`](https://nextmail.sh/docs/php/reference/suppressions#list); Go [`Suppressions.List`](https://nextmail.sh/docs/go/reference/suppressions#list); Java [`suppressions().list`](https://nextmail.sh/docs/java/reference/suppressions#list); C# [`Suppressions.ListAsync`](https://nextmail.sh/docs/csharp/reference/suppressions#list); CLI [`nextmail suppressions list`](https://nextmail.sh/docs/cli/reference/suppressions#suppressions-list).

### `suppressions.list_all()`

Collect every suppressed address into one list

```python
def list_all(
    *,
    limit: int | None = None,
    cursor: str | None = None,
    q: str | None = None,
    reason: SuppressionReason | None = None,
    api_key: str | None = None,
    timeout: float | None = None,
) -> builtins.list[SuppressionResource]
```

Walks every page of `list` and returns every suppressed address in one list, newest first. One request per page, with the same filters on each.

Scopes: `settings:read`.

**Parameters**

- `limit` (`int`): Page size for each request, from 1 to 100. The server defaults to 25.
- `cursor` (`str`): Starts the walk after this cursor instead of the first page.
- `q` (`str`): Searches the address, the reason and the detail. Words match loosely, and a close spelling is tried when nothing matches exactly.
- `reason` (`SuppressionReason`): Keeps one kind: `bounce`, `complaint` or `manual`.
- `api_key` (`str`): Overrides the client API key for every page of this walk.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `NextmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`list[SuppressionResource]` holding every suppressed address.

**Example**

```python
from nextmail import nextmail

blocked = {row['email'] for row in nextmail.suppressions.list_all(limit=100)}
recipients = ['ada@example.com', 'grace@example.com', 'linus@example.com']

print([email for email in recipients if email not in blocked])
```

**Notes**

- If any page fails, the call raises and the rows already fetched are discarded.

Also available in: API [`GET /suppressions`](https://nextmail.sh/docs/api/reference/suppressions#get-suppressions); TypeScript [`nextmail.suppressions.listAll()`](https://nextmail.sh/docs/sdk/reference/suppressions#listAll); Ruby [`suppressions.list_all`](https://nextmail.sh/docs/ruby/reference/suppressions#listAll); PHP [`suppressions->listAll`](https://nextmail.sh/docs/php/reference/suppressions#listAll); Go [`Suppressions.ListAll`](https://nextmail.sh/docs/go/reference/suppressions#listAll); Java [`suppressions().listAll`](https://nextmail.sh/docs/java/reference/suppressions#listAll); C# [`Suppressions.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/suppressions#listAll).

### `suppressions.iterate()`

Stream the suppression list one address at a time

```python
def iterate(
    *,
    limit: int | None = None,
    cursor: str | None = None,
    q: str | None = None,
    reason: SuppressionReason | None = None,
    api_key: str | None = None,
    timeout: float | None = None,
) -> Iterator[SuppressionResource]
```

Returns a generator that yields one suppressed address at a time, newest first, and requests the next page only once the current one is used up. Nothing is fetched until the loop starts, and breaking out of it stops the requests.

Scopes: `settings:read`.

**Parameters**

- `limit` (`int`): Page size for each request, from 1 to 100. The server defaults to 25.
- `cursor` (`str`): Starts the walk after this cursor instead of the first page.
- `q` (`str`): Searches the address, the reason and the detail. Words match loosely, and a close spelling is tried when nothing matches exactly.
- `reason` (`SuppressionReason`): Keeps one kind: `bounce`, `complaint` or `manual`.
- `api_key` (`str`): Overrides the client API key for every page of this walk.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `NextmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`Iterator[SuppressionResource]`, a generator yielding one suppressed address per step.

**Example**

```python
from nextmail import nextmail

for row in nextmail.suppressions.iterate(q='example.com'):
    print(row['email'], row['reason'], row['removable'])
```

**Notes**

- The generator is lazy, so an abandoned loop costs only the pages you consumed.

Also available in: API [`GET /suppressions`](https://nextmail.sh/docs/api/reference/suppressions#get-suppressions); TypeScript [`nextmail.suppressions.iterate()`](https://nextmail.sh/docs/sdk/reference/suppressions#iterate); Ruby [`suppressions.iterate`](https://nextmail.sh/docs/ruby/reference/suppressions#iterate); PHP [`suppressions->iterate`](https://nextmail.sh/docs/php/reference/suppressions#iterate); Go [`Suppressions.Iterate`](https://nextmail.sh/docs/go/reference/suppressions#iterate); Java [`suppressions().iterate`](https://nextmail.sh/docs/java/reference/suppressions#iterate); C# [`Suppressions.IterateAsync`](https://nextmail.sh/docs/csharp/reference/suppressions#iterate).

### `suppressions.get()`

Read one suppressed address by id

```python
def get(
    id: str,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> SuppressionResource
```

Returns one row of the suppression list: the address, why it is there, the detail the bounce or complaint carried, whether it can be removed and when it was added.

Scopes: `settings:read`.

**Parameters**

- `id` (`str`, required): The id from `list`.
- `api_key` (`str`): Overrides the client API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `NextmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`SuppressionResource` with `id`, `email`, `reason`, `detail`, `removable` and `createdAt`.

**Example**

```python
from nextmail import nextmail

row = nextmail.suppressions.get('7b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e')

print(row['email'], row['reason'], row['removable'])
```

**Notes**

- An id that is not on this workspace is a 404 `resource_not_found`.

Also available in: API [`GET /suppressions/{id}`](https://nextmail.sh/docs/api/reference/suppressions#get-suppressions-id); TypeScript [`nextmail.suppressions.get()`](https://nextmail.sh/docs/sdk/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).

### `suppressions.add()`

Stop sending to an address

```python
def add(
    body: SuppressionAdd,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> SuppressionResource
```

Puts an address on the suppression list by hand, with `reason` set to `manual`, so no address in the workspace sends to it again until it is removed. It is the Block an address control on the Blocked addresses screen.

Adding an address that is already there changes nothing: the server answers 200 with the row it already holds, whatever its reason, where a new entry answers 201. Either way you get the row back. A new entry fires `suppression.added` to the webhooks that asked for it.

Scopes: `settings:write`.

**Parameters**

- `body['email']` (`str`, required): The address to stop sending to. It is trimmed and lower cased.
- `api_key` (`str`): Overrides the client API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `NextmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`SuppressionResource` for the address, new or already there.

**Example**

```python
from nextmail import nextmail

row = nextmail.suppressions.add({'email': 'noreply@example.com'})

print(row['reason'], row['createdAt'])
```

**Notes**

- Safe to repeat: a second add finds the first entry, so the SDK retries it after a network failure.
- A key limited to particular addresses or domains is refused with 422 `capability_unsupported`, because the list stops mail from every address in the workspace. So is an app connected by anybody but the owner.

Also available in: API [`POST /suppressions`](https://nextmail.sh/docs/api/reference/suppressions#post-suppressions); TypeScript [`nextmail.suppressions.add()`](https://nextmail.sh/docs/sdk/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).

### `suppressions.remove()`

Allow mail to an address again

```python
def remove(
    id: str,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> RemovedSuppressionResource
```

Takes an address off the suppression 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. A hard bounce answers 409 `suppression_not_removable` and stays, because the address could not take mail: check it is spelled right and send to the corrected one instead.

Scopes: `settings:write`.

**Parameters**

- `id` (`str`, required): The id from `list`.
- `api_key` (`str`): Overrides the client API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `NextmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`RemovedSuppressionResource` with `object` set to `suppression`, the `id` and `email`, and `deleted` set to `True`.

**Example**

```python
from nextmail import NextmailApiError, nextmail

try:
    removed = nextmail.suppressions.remove('7b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e')
except NextmailApiError as error:
    if error.code != 'suppression_not_removable':
        raise
    print('A hard bounce stays on the list. Check the spelling of the address.')
else:
    print('Mail may go to', removed['email'], 'again')
```

**Notes**

- The SDK does not retry a delete. A 404 on your own second attempt after a lost response means the first one worked.
- A key limited to particular addresses or domains is refused with 422 `capability_unsupported`.

Also available in: API [`DELETE /suppressions/{id}`](https://nextmail.sh/docs/api/reference/suppressions#delete-suppressions-id); TypeScript [`nextmail.suppressions.remove()`](https://nextmail.sh/docs/sdk/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).

### `suppressions.list_unsubscribes()`

List one page of the people who unsubscribed

```python
def list_unsubscribes(
    *,
    limit: int | None = None,
    cursor: str | None = None,
    q: str | None = None,
    source: UnsubscribeSource | None = None,
    api_key: str | None = None,
    timeout: float | None = None,
) -> Page[UnsubscribeResource]
```

Returns one page of 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 your replies, still reach them, because only marketing mail stops. `list` is the hard block on every kind of mail.

`removable` says whether `remove_unsubscribe` takes it back, which is true only for one the team recorded by hand. 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.

Scopes: `settings:read`.

**Parameters**

- `limit` (`int`): Page size, from 1 to 100. The server defaults to 25.
- `cursor` (`str`): The `nextCursor` of the previous page. Leave it out for the first page.
- `q` (`str`): One whole address, matched exactly and without regard to case. The addresses are stored encrypted, so a part of one finds nothing.
- `source` (`UnsubscribeSource`): Keeps one way of unsubscribing: `link`, `one_click`, `complaint`, `import` or `manual`.
- `api_key` (`str`): Overrides the client API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `NextmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`Page[UnsubscribeResource]`, a dict with `items`, `hasMore` and `nextCursor`. Each item has `email`, `source`, `broadcastId`, `automationId`, `removable` and `createdAt`.

**Example**

```python
from nextmail import nextmail

page = nextmail.suppressions.list_unsubscribes(source='one_click')

for row in page['items']:
    print(row['email'], row['createdAt'])

ada = nextmail.suppressions.list_unsubscribes(q='ada@example.com')
print(len(ada['items']) > 0)
```

**Notes**

- Needs `settings:read`, the scope the Blocked addresses screen in Settings is gated on.
- The cursor is opaque and holds where the last row sat. A cursor this list did not hand out is a 400 `invalid_cursor`.

Also available in: API [`GET /suppressions/unsubscribes`](https://nextmail.sh/docs/api/reference/suppressions#get-suppressions-unsubscribes); TypeScript [`nextmail.suppressions.listUnsubscribes()`](https://nextmail.sh/docs/sdk/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).

### `suppressions.add_unsubscribe()`

Record that somebody unsubscribed

```python
def add_unsubscribe(
    body: UnsubscribeAdd,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> UnsubscribeResource
```

Records that somebody asked to stop getting marketing mail, for when they asked by phone, in a reply or anywhere else, with `source` set to `manual`. Their contact, if there is one, is unsubscribed from every audience at once, the automations sending to them end, and `contact.unsubscribed` fires. No broadcast or automation email goes to the address from then on, while ordinary mail and replies still do.

Recording an address that is already on the list changes nothing: the server answers 200 with the record it holds, where a new one answers 201.

Scopes: `settings:write`.

**Parameters**

- `body['email']` (`str`, required): The address that asked for no more marketing mail. It is trimmed and lower cased.
- `api_key` (`str`): Overrides the client API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `NextmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`UnsubscribeResource` for the address, new or already there.

**Example**

```python
from nextmail import nextmail

row = nextmail.suppressions.add_unsubscribe({'email': 'ada@example.com'})

print(row['source'], row['removable'])
```

**Notes**

- Safe to repeat: a second call finds the first record, so the SDK retries it after a network failure.
- A key limited to particular addresses or domains is refused with 422 `capability_unsupported`, because the list covers every address in the workspace. So is an app connected by anybody but the owner.

Also available in: API [`POST /suppressions/unsubscribes`](https://nextmail.sh/docs/api/reference/suppressions#post-suppressions-unsubscribes); TypeScript [`nextmail.suppressions.addUnsubscribe()`](https://nextmail.sh/docs/sdk/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).

### `suppressions.remove_unsubscribe()`

Take back an unsubscribe the team recorded

```python
def remove_unsubscribe(
    email: str,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> RemovedUnsubscribeResource
```

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 kind 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. An address that has not unsubscribed is a 404.

Scopes: `settings:write`.

**Parameters**

- `email` (`str`, required): The address, as `list_unsubscribes` returns it. Case does not matter.
- `api_key` (`str`): Overrides the client API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `NextmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`RemovedUnsubscribeResource` with `object` set to `unsubscribe`, the `email`, and `deleted` set to `True`.

**Example**

```python
from nextmail import NextmailApiError, nextmail

try:
    removed = nextmail.suppressions.remove_unsubscribe('ada@example.com')
except NextmailApiError as error:
    if error.code != 'unsubscribe_not_removable':
        raise
    print('Only the person can subscribe again.')
else:
    print(removed['email'], 'may get marketing mail again')
```

**Notes**

- The SDK does not retry a delete. A 404 on your own second attempt after a lost response means the first one worked.
- A key limited to particular addresses or domains is refused with 422 `capability_unsupported`.

Also available in: API [`DELETE /suppressions/unsubscribes/{email}`](https://nextmail.sh/docs/api/reference/suppressions#delete-suppressions-unsubscribes-email); TypeScript [`nextmail.suppressions.removeUnsubscribe()`](https://nextmail.sh/docs/sdk/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).