Suppressions API

A suppression is an address SMTPfast will not send to. Every send is checked against the list first, so a suppressed recipient is refused before it reaches the provider. Most entries arrive on their own: a hard bounce or a spam complaint adds the address automatically, which is what protects your sending reputation. You can also add addresses yourself, and remove one when a customer asks to start receiving mail again.

Scope

Reading needs contact:read. Adding or removing needs contact:write. Suppressions belong to a team, so a key only ever sees its own team's list.

What a suppression blocks

Each suppression has a scope, which decides which of your emails it stops. Emails are marketing or transactional.

all: no email goes to the address. Hard bounces and complaints have this scope, and so does a manual suppression unless you ask for another.
marketing: marketing email is blocked, and email you label transactional still goes out. A recipient who clicks your unsubscribe link gets this scope, so they keep getting the receipts and password resets you label transactional. Unlabelled email is marketing, so it is blocked. You can also add a manual suppression with this scope, by passing "scope": "marketing".

There is one suppression per address. If a hard bounce, a complaint or a manual suppression with scope all arrives for an address that has a marketing one, it becomes all with the new reason. An unsubscribe never narrows a suppression that is already all.

Unsubscribes recorded before marketing-only unsubscribes existed have scope all and keep blocking every email. To let email you label transactional through to one of those addresses, delete the suppression and add it again with scope marketing. Broadcasts also skip any contact marked unsubscribed.

GET/v1/suppressions

List suppressed addresses, newest first, with counts by reason. Each one carries its scope: all or marketing.

Parameters

Parameter	Type	Required	Description
q	string	No	Filter by address, matched as a substring
reason	string	No	hard_bounce, complaint, manual, or all. Defaults to all.
limit	number	No	1 to 100. Defaults to 50.
page	number	No	1-based page number. Defaults to 1.

Response

json

{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "id": "sup_01j9x3p2q7",
      "email": "[email protected]",
      "reason": "hard_bounce",
      "source": "ses",
      "scope": "all",
      "bounce_type": "permanent",
      "created_at": "2026-09-03T08:12:44.000Z"
    }
  ],
  "page": 1,
  "page_size": 50,
  "filtered_total": 412,
  "total": 412,
  "hard_bounces": 388,
  "complaints": 19,
  "manual": 5
}

POST/v1/suppressions

Suppress an address yourself. Use this when someone asks to be removed outside your own unsubscribe flow.

Parameters

Parameter	Type	Required	Description
email	string	Yes	The address to suppress
reason	string	No	Only manual is accepted. Defaults to manual.
scope	string	No	all (the default) blocks every email to the address. marketing blocks marketing email only. An address already suppressed keeps its suppression, except that scope all turns a marketing one into a manual suppression of every email.

GET/v1/suppressions/{id}

Retrieve one suppression, including why it was added and which email caused it.

DELETE/v1/suppressions/{id}

Remove a suppression so the address can receive mail again. Returns 404 if the id does not belong to your team.

Adding and removing

curl -X POST https://smtpfa.st/api/v1/suppressions \
  -H "Authorization: Bearer $SMTPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "reason": "manual" }'

# stop marketing email only; receipts and password resets still go out
curl -X POST https://smtpfa.st/api/v1/suppressions \
  -H "Authorization: Bearer $SMTPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "scope": "marketing" }'

# remove one, for example after a customer asks to be resubscribed
curl -X DELETE https://smtpfa.st/api/v1/suppressions/sup_01j9x3p2q7 \
  -H "Authorization: Bearer $SMTPFAST_API_KEY"

Before you remove one

A hard bounce means the mailbox does not exist. Removing that suppression and sending again produces another bounce, and repeated bounces are what damages a sending reputation. A complaint means the recipient marked your mail as spam; sending to them again is what gets a domain blocked. Removing those is worth doing only when you know something has changed, such as a customer confirming a corrected address.

Batches

Add or remove up to 100 suppressions in one call. These match Resend's batch endpoints.

POST/v1/suppressions/batch/add

Suppress up to 100 addresses as manual suppressions of every email (scope all). An address with a marketing suppression is moved to all.

Parameters

Parameter	Type	Required	Description
emails	string[]	Yes	1 to 100 addresses

Request Body

json

{ "emails": ["[email protected]", "[email protected]"] }

Response

json

{ "object": "list", "data": [ { "object": "suppression", "id": "sup_...", "email": "[email protected]" } ] }

POST/v1/suppressions/batch/remove

Remove up to 100 suppressions by emails or by ids, not both. Owners and admins only.

Parameters

Parameter	Type	Required	Description
emails	string[]	No	1 to 100 addresses
ids	string[]	No	1 to 100 suppression ids

Request Body

json

{ "ids": ["sup_1"] }

Response

json

{ "object": "list", "data": [ { "object": "suppression", "id": "sup_1", "email": "[email protected]", "deleted": true } ] }