Suppressions
The per-tenant do-not-send list — how sends get blocked, and how to manage the list.
If a recipient is on your suppression list, the send returns 200 with
{ "status": "suppressed" } and no message is sent — protecting your
sender reputation and your bill. Suppression is checked after validation and
before the queue, and the consumed quota unit is refunded.
How entries get there
| Source | Reason | Who sets it |
|---|---|---|
| Hard bounce event | hard_bounce | events pipeline (automatic) |
| Complaint (spam report) | complaint | events pipeline (manual or automatic) |
| Unsubscribe / preference centre | unsubscribe | events pipeline |
| Manual / API | manual | you |
The events pipeline owns the verified reasons; anything added through the API
is always stored as manual (a reason you send is accepted but ignored).
Managing the list
| Endpoint | Purpose |
|---|---|
GET /v1/suppressions | List, newest first (?limit=, ?cursor=) |
POST /v1/suppressions | Add one (upsert on (tenant_id, email)) |
POST /v1/suppressions/bulk | Add up to 100 at once |
DELETE /v1/suppressions/bulk | Remove up to 100 at once |
DELETE /v1/suppressions/{email} | Remove one (always 200 { "deleted": true }) |
{ "email": "ada@lovelace.io" }{ "email": "ada@lovelace.io", "reason": "manual" }Suppressed ≠ error
A suppressed recipient is a 200, not a 4xx — your integration should
treat it as a normal outcome. Batch sends report it per message as
status: "suppressed".
Removing an entry
DELETE /v1/suppressions/{email} lifts the block. Do this only when the
recipient asks to hear from you again — removing hard bounces and complaints
without consent puts your domain reputation back at risk.