Suppressions

Manage your email suppression list. Suppressed email addresses are automatically skipped when sending emails. Suppressions are created automatically from bounces and complaints, or can be added manually via the API.

List Suppressions

GET

/suppressions

List suppressed email addresses with pagination and filtering

Name	Type	Required	Description
limit	integer	Optional	Number of results to return (default: 50, max: 1000)
offset	integer	Optional	Number of results to skip for pagination (default: 0)
reason	string	Optional	Filter by suppression reason: bounce, complaint, manual, or unsubscribe

curl "https://api.topmail.so/api/v1/suppressions?limit=20&reason=bounce" \
  -H "Authorization: Bearer tm_live_abc123"

{
  "data": [
    {
      "id": "supp-uuid-12345",
      "email": "bounced@example.com",
      "reason": "bounce",
      "bounce_type": "Permanent",
      "bounce_sub_type": "General",
      "complaint_type": null,
      "suppressed_at": "2025-01-10T14:30:00.000Z",
      "reactivated_at": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

Add Suppression

POST

/suppressions

Manually add an email address to the suppression list

Name	Type	Required	Description
email	string	Required	Email address to suppress

curl -X POST https://api.topmail.so/api/v1/suppressions \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "unsubscribed@example.com"
  }'

{
  "data": {
    "email": "unsubscribed@example.com",
    "suppressed": true
  }
}

Remove Suppression

DELETE

/suppressions/:email

Remove an email address from the suppression list

Name	Type	Required	Description
email	string	Required	Email address to remove from suppression (URL parameter)

curl -X DELETE https://api.topmail.so/api/v1/suppressions/user@example.com \
  -H "Authorization: Bearer tm_live_abc123"

{
  "data": {
    "email": "user@example.com",
    "suppressed": false
  }
}

Caution

Removing a suppression for an address that previously bounced or complained may harm your sender reputation. Only remove suppressions when you are confident the address is valid and the recipient wants to receive emails.