> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Suppressions API

> Filter, import, export, and remove suppressed email addresses with the v2 API.

Use suppressions to prevent delivery to addresses that should no longer receive mail. In the dashboard, open **Suppressions** to view the list, **Export** it, or **Import suppressions**.

## Authentication

**Base URL:** `https://pro.api.serversmtp.com/api/v2`

Send `consumerKey` and `consumerSecret` headers with **Statistics & Management APIs** (`APIS`) permission. Its IP restrictions must allow your server. See [authentication](/docs/api-reference/authentication.md).

## List suppressions

`GET /suppressions` requires `from` and `to` in `YYYY-MM-DD` format. Do not include a time.

```bash Terminal theme={"system"}
curl --get 'https://pro.api.serversmtp.com/api/v2/suppressions' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET' \
  --data-urlencode 'from=2026-10-01' \
  --data-urlencode 'to=2026-10-27' \
  --data-urlencode 'filter_by=bounce' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=10'
```

| Parameter | Description |
| - | - |
| `from`, `to` | Required dates. `from` must be on or before `to`. |
| `page`, `limit` | Positive integers; defaults `1` and `10`. |
| `filter` | Search text for recipient, subject, or reason. Matches whole words, not parts of words: `example.net` and `Reset` match, `exam` does not. For partial matches on sender or recipient, use `restrict` rules with `POST /suppressions`. |
| `filter_by` or `filter_by[]` | Suppression sources to include. Pass a comma-separated `filter_by=bounce,spam` or repeat `filter_by[]` for each source. Repeating plain `filter_by` keeps only the last value. |
| `smart_search` | Boolean search option. |
| `orderby` | `date` (default), `source`, `recipient`, or `reason`. |
| `ordertype` | `asc` or `desc`. |
| `tz` | Timezone offset, such as `+01:00`. URL-encode the plus sign. |

An invalid `orderby`, `ordertype`, `page`, or `limit` returns `400` with `orderby_can_only_be_date_or_source_or_recipient_or_reason`, `ordertype_should_be_asc_or_desc`, `page_should_be_integer`, `page_should_be_greater_than_0`, `limit_should_be_integer`, or `limit_should_be_greater_than_0`.

The response is an object with `count` and `results`:

```json theme={"system"}
{
  "count": 1,
  "results": [
    {
      "date": "2026-10-20 10:30:00",
      "source": "bounce",
      "recipient": "recipient@example.net",
      "reason": "550 mailbox not found",
      "sender": "sender@example.com",
      "subject": "Order update"
    }
  ]
}
```

### Sources

| API value | Dashboard type |
| - | - |
| `manual` | Manual |
| `bounce` | Bounce |
| `spam` | Spam |
| `unsubscribe` | Unsubscribe |
| `validation_failed` | Validation failed |

## Filter with a JSON body

`POST /suppressions` retrieves filtered results. To add addresses, use the [import endpoint](#import-addresses).

```bash Terminal theme={"system"}
curl -X POST 'https://pro.api.serversmtp.com/api/v2/suppressions' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "2026-10-01",
    "to": "2026-10-27",
    "filter_by": ["bounce"],
    "page": 1,
    "limit": 10,
    "restrict": [
      {"by":"recipient","operator":"include","filter":"example.net","smart_search":false}
    ]
  }'
```

The JSON body supports the list filters, sorting, and pagination. `restrict` is an array of rules with `by` (`sender`, `recipient`, `reason`, or `subject`), `operator` (`include` or `exclude`), `filter`, and `smart_search`. The response uses the same `count` and `results` envelope.

## Import addresses

`POST /suppressions/import` accepts a JSON array of addresses in `content`, with `type: "manual"` and an optional `reason`:

```bash Terminal theme={"system"}
curl -X POST 'https://pro.api.serversmtp.com/api/v2/suppressions/import' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "manual",
    "content": ["optout@example.net"],
    "reason": "Removal request"
  }'
```

To upload a CSV or TXT file with one address per line, use multipart fields `type=file`, `file`, and optional `reason`:

```bash Terminal theme={"system"}
curl -X POST 'https://pro.api.serversmtp.com/api/v2/suppressions/import' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET' \
  -F 'type=file' \
  -F 'file=@/path/to/suppressions.csv' \
  -F 'reason=Removal requests'
```

The response contains `status`, `valid` (accepted addresses), and `invalid` (rejected values).

## Export CSV

`GET /suppressions/csv` accepts the date, search, source, sorting, and timezone query parameters, without pagination, and validates them like the list. `POST /suppressions/csv` accepts a JSON filter body with required `from` and `to` and optional `filter`, `filter_by`, `smart_search`, `tz`, and `restrict`. Both return CSV data.

## Remove up to 100 addresses

`POST /suppressions/bulk_delete` takes a bare JSON array of email addresses, with a maximum of 100 addresses per request:

```bash Terminal theme={"system"}
curl -X POST 'https://pro.api.serversmtp.com/api/v2/suppressions/bulk_delete' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET' \
  -H 'Content-Type: application/json' \
  -d '["recipient@example.net"]'
```

A successful request returns `{"success":true}`.

## Remove matching suppressions

`POST /suppressions/delete` takes a filter body with required dates and optional `filter`, `filter_by`, `smart_search`, `tz`, and `restrict`. Review the matching records with `POST /suppressions` before deleting them.

```bash Terminal theme={"system"}
curl -X POST 'https://pro.api.serversmtp.com/api/v2/suppressions/delete' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "2026-10-01",
    "to": "2026-10-27",
    "filter_by": ["manual"],
    "restrict": [
      {"by":"recipient","operator":"include","filter":"recipient@example.net","smart_search":false}
    ]
  }'
```

A successful request returns `{"success":true}`. Remove an address only when you have resolved the reason for suppression and have permission to email it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.