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.

ReasonHow the address gets on the list
hard_bounceAutomatically, when the receiving server permanently rejects the address, for example with 550 5.1.1 User unknown.
spam_complaintAutomatically, when a spam complaint for the address arrives through a feedback loop.
unsubscribeAdded by you when someone opts out.
manualAdded 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

GET/api/v1/suppressionsRequires suppressions:read
curl "https://mail.example.com/api/v1/suppressions?q=example.com&limit=50" \
  -H "Authorization: Bearer $MAILFORGE_API_KEY"
Query parameters
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.
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"
    }
  ],
  "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

POST/api/v1/suppressionsRequires suppressions:manage
curl -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"
  }'
Body parameters
emailstringrequired
The address to suppress.
reasonstring
manual (default), unsubscribe, hard_bounce or spam_complaint.
detailstring
A note, up to 500 characters.

Response

201 Created
{
  "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

DELETE/api/v1/suppressions/{id}Requires suppressions:manage

The 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"
Response
{
  "ok": true,
  "id": "d2f684a6-7134-4bd8-bcb4-b62c30dd604e"
}