# List suppressions

> See which addresses your project does not send to, and why.

`GET https://api-connect.nxiom.com/api/v1/emails/suppressions`

## Authorization

Requires `email.full_access`.

## Query parameters

| Field | Type | Description |
| --- | --- | --- |
| `search` | string · optional | Part of an email address, 1–255 characters. |
| `limit` | integer · optional | 1–100; defaults to 50. |
| `cursor` | string · optional | The previous response's `nextCursor`. |

## Request

### cURL

```shell
curl "https://api-connect.nxiom.com/api/v1/emails/suppressions?search=example.com&limit=50" \
  -H "Authorization: Bearer $NEXIOM_API_KEY"
```

### Node.js

```typescript
import { NexiomConnect } from '@nexiom/connect';

const apiKey = process.env.NEXIOM_API_KEY;
if (!apiKey) throw new Error('Set NEXIOM_API_KEY');

const nexiom = new NexiomConnect({ apiKey });

const { data, error } = await nexiom.emails.suppressions.list({ search: 'example.com', limit: 50 });

if (error) throw new Error(`${error.code}: ${error.message}`);
for (const suppression of data.items) {
  console.log(suppression.email, suppression.reason);
}

// Pass nextCursor as cursor while hasMore is true.
console.log(data.hasMore, data.nextCursor);
```

### PHP

```php
<?php

use Nexiom\Connect\NexiomConnect;

$apiKey = getenv('NEXIOM_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set NEXIOM_API_KEY');
}

$nexiom = new NexiomConnect($apiKey);

$page = $nexiom->emails->suppressions->list(['search' => 'example.com', 'limit' => 50]);

foreach ($page['items'] as $suppression) {
    echo $suppression['email'], ' ', $suppression['reason'], PHP_EOL;
}
```

## Response

HTTP `200`. Addresses are listed alphabetically, once each. Sends to a listed address are created with status `suppressed` and are not delivered or counted toward your allowance. Continue with `nextCursor` while `hasMore` is true.

| Field | Type | Description |
| --- | --- | --- |
| `email` | string | The suppressed address. |
| `reason` | string | Why it is suppressed. When an address has several reasons, the one that applies to your sends. |

| Reason | Meaning |
| --- | --- |
| `hard_bounce` | Email could not be delivered to this address. |
| `complaint` | The recipient reported an email as spam. |
| `unsubscribed` | The recipient unsubscribed. |
| `invalid` | The address cannot receive email. |
| `manual` | Delivery to this address is blocked. |
| `temporary_failure` | Recent deliveries failed temporarily; the suppression expires on its own. |

The list covers suppressions for your project and its organization. A send can also be suppressed for reasons that are not listed here, such as a contact who unsubscribed in [Contacts](/docs/learn/contacts) or a block that applies across Nexiom Connect; [retrieve the email](/docs/api/emails/retrieve) to see the `delivery_reason` of a specific send.

### 200 OK

Example successful response.

```json
{
  "message": "Email suppressions fetched",
  "data": {
    "items": [
      {
        "email": "gone@example.com",
        "reason": "hard_bounce"
      },
      {
        "email": "reader@example.com",
        "reason": "unsubscribed"
      }
    ],
    "nextCursor": null,
    "hasMore": false
  }
}
```

### 400 Bad Request

The request is invalid. Correct it before retrying; `details` lists the failing fields.

```json
{
  "error": "invalid_argument",
  "message": "Request doesn't match the schema",
  "correlationId": "req_example",
  "details": {
    "context": "body",
    "issues": []
  }
}
```

### 401 Unauthorized

The API key is missing, malformed, revoked, or expired.

```json
{
  "error": "unauthorized",
  "message": "Invalid API key",
  "correlationId": "req_example"
}
```

### 403 Forbidden

The API key lacks a required permission, or its domain restriction does not allow this sender.

```json
{
  "error": "not_allowed",
  "message": "Missing required API key permissions: email.full_access",
  "correlationId": "req_example"
}
```

---

Source: https://connect.nxiom.com/docs/api/emails/suppressions