Suppressions 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.

List suppressions

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

Terminal

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:

{
  "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.

Terminal

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:

Terminal

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:

Terminal

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:

Terminal

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.

Terminal

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.

Overview

Endpoints

Authentication

List suppressions

Sources

Filter with a JSON body

Import addresses

Export CSV

Remove up to 100 addresses

Remove matching suppressions

​Authentication

​List suppressions

​Sources

​Filter with a JSON body

​Import addresses

​Export CSV

​Remove up to 100 addresses

​Remove matching suppressions

Authentication

List suppressions

Sources

Filter with a JSON body

Import addresses

Export CSV

Remove up to 100 addresses

Remove matching suppressions