Suppressions

The suppression list stops mail to an address before the platform queues it. The worker adds hard bounces and complaints automatically, and the third soft bounce within 7 days; unsubscribes add themselves. This API manages manual entries and reads the whole list. The console has the same controls (see Suppressions).

List suppressions

GET /api/v1/suppressions?email=&reason=manual&limit=25&cursor=…

Newest first. reason is one of hard_bounce, complaint, manual, unsubscribe. Pagination works like List emails.

{
  "object": "list",
  "data": [
    { "object": "suppression", "id": "cmfa…", "email": "dead@example.org", "reason": "hard_bounce", "domain": null, "source": "event:cmf9…", "expires_at": null, "created_at": "2026-08-18T09:12:40.000Z" }
  ],
  "next_cursor": null
}

domain is null for an organization-wide entry, or the domain name for a scoped one.

Add a suppression

POST /api/v1/suppressions

Field	Required	Notes
email	yes	Lower-cased.
domain	no	Scope to one verified domain of the organization; omit for organization-wide.
expires_at	no	ISO 8601 with offset. The platform ignores the entry after this time.
note	no	Stored as source (up to 500 characters).

SEND and FULL keys can add; f5_test_ keys cannot (403 test_key_not_allowed). The platform upserts on (organization, scope, email), so a repeat answers 201 with the same id.

Reasons have a precedence: complaint > hard_bounce > unsubscribe > manual. This endpoint creates or updates manual entries only. When the address already has a stronger entry at that scope, the call answers 409 suppression_conflict and changes nothing. An expired entry counts as absent. The worker and the unsubscribe links follow the same rule: they upgrade a weaker entry, clear its expiry, and never downgrade a stronger one. A domain-restricted key must pass domain and can only name its own domains (403 forbidden_domain); it also lists and deletes only entries scoped to those domains.

Remove a suppression

DELETE /api/v1/suppressions/:id

FULL keys only — removing an entry lets mail flow to that address again. Answers { "object": "suppression", "id", "deleted": true }, or 404 not_found for an id outside the organization.