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.

GET/v1/suppressions

List suppressed addresses, newest first, with counts by reason.

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

{
  "data": [
    {
      "id": "sup_01j9x3p2q7",
      "email": "[email protected]",
      "reason": "hard_bounce",
      "source": "ses",
      "bounce_type": "permanent",
      "created_at": "2026-09-03T08:12:44.000Z"
    }
  ],
  "counts": { "total": 412, "hard_bounce": 388, "complaint": 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	hard_bounce, complaint or manual. Defaults to manual.

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" }'

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

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 } ] }