Suppressions
The list of addresses MailForge will not send to, and how bounces get onto it.
How suppression works
Sending again and again to addresses that do not exist or do not want your mail damages your sender reputation. Each workspace therefore has a suppression list. Before an email is sent, the worker removes every recipient that is on it.
| Reason | How the address gets on the list |
|---|---|
hard_bounce | Automatically, when the receiving server permanently rejects the address, for example with 550 5.1.1 User unknown. |
spam_complaint | Automatically, when a spam complaint for the address arrives through a feedback loop. |
unsubscribe | Added by you when someone opts out. |
manual | Added by you for any other reason. |
If some recipients of an email are suppressed, it goes to the others. If all of them are, the email ends with the status suppressed and nothing is sent. Both cases trigger the webhook event email.suppressed, which names the skipped addresses.
List suppressions
/api/v1/suppressionsRequires suppressions:readcurl "https://mail.example.com/api/v1/suppressions?q=example.com&limit=50" \
-H "Authorization: Bearer $MAILFORGE_API_KEY"qstring- Search text, for example a domain or part of an address.
limitinteger- 1 to 200. Defaults to 100.
offsetinteger- Number of entries to skip. Defaults to 0.
{
"data": [
{
"id": "d2f684a6-7134-4bd8-bcb4-b62c30dd604e",
"email": "optout@example.com",
"reason": "unsubscribe",
"detail": "Asked by phone",
"source_email_id": null,
"created_at": "2026-11-20T20:02:46.095Z"
}
],
"total": 1
}source_email_id is the email that caused an automatic entry. total is the number of entries that match, across all pages.
Add an address
/api/v1/suppressionsRequires suppressions:managecurl -X POST https://mail.example.com/api/v1/suppressions \
-H "Authorization: Bearer $MAILFORGE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "optout@example.com",
"reason": "unsubscribe",
"detail": "Asked by phone"
}'emailstringrequired- The address to suppress.
reasonstringmanual(default),unsubscribe,hard_bounceorspam_complaint.detailstring- A note, up to 500 characters.
Response
{
"data": {
"id": "d2f684a6-7134-4bd8-bcb4-b62c30dd604e",
"email": "optout@example.com",
"reason": "unsubscribe",
"detail": "Asked by phone",
"source_email_id": null,
"created_at": "2026-11-20T20:02:46.095Z"
},
"created": true
}If the address is already on the list, the response is 200 with created: false and the existing entry.
Remove an address
/api/v1/suppressions/{id}Requires suppressions:manageThe address may receive mail again. Only remove a bounced address when you know the mailbox exists now.
curl -X DELETE https://mail.example.com/api/v1/suppressions/d2f684a6-7134-4bd8-bcb4-b62c30dd604e \
-H "Authorization: Bearer $MAILFORGE_API_KEY"{
"ok": true,
"id": "d2f684a6-7134-4bd8-bcb4-b62c30dd604e"
}