Suppressions

A suppression is an address Mailfully will not deliver to. Entries are created automatically from hard bounces and spam complaints, or manually. One list covers both your test and live environments. The dashboard shows this list on the Blocklist page.

What gets suppressed automatically

Transient and undetermined bounces never suppress. A soft bounce adds no entry, changes no message status, and emits no webhook. Addresses are stored lowercased.

Bounces in test mode suppress the simulator address, never the recipient you requested. See Why an address was suppressed for tracing a specific entry back to the bounce, complaint, or manual add that created it.

Sending to a suppressed address

Sends to suppressed addresses are not rejected. You get no error. At accept time, suppressed recipients are silently dropped from to, cc, and bcc:

• Some recipients suppressed: the message sends to the remaining recipients.
• All to recipients suppressed: you still get 202 and a message id, but the message has status canceled. Nothing is sent or billed, but its recipients still count toward the daily limit.

A race window also exists: an address can be suppressed between accept and send (for example, by a hard bounce landing moments earlier). A pre-send guard re-checks every recipient immediately before dispatch. If all to recipients are suppressed by then, the message flips to status failed with last_event: "suppressed", and a synthetic suppressed event listing every dropped recipient is written to the message's event timeline.

List and filter suppressions

Listing requires the read:suppressions scope, which can be minted onto an API key. An mf_ key works here.

curl "https://api.mailfully.com/v1/suppressions?email=ada@example.com" \
  -H "Authorization: Bearer mf_live_xxxxxxxxxxxx"

{
  "data": [
    {
      "id": "01J1F5S8ZG9Q2W7X4V3B2N1M0K",
      "email": "ada@example.com",
      "reason": "hard_bounce",
      "source": "ses_notification",
      "created_at": "2026-07-08T14:23:07.123Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Query parameters:

• email: exact match. Stored values are canonical lowercase, so lowercase your query or it will not match.
• reason: exact match against hard_bounce, complaint, or manual.
• limit: default 25, max 100.
• cursor: opaque cursor from a previous page's next_cursor.

See List suppressions for the full schema.

Add a suppression manually

Adding and removing entries needs the session-only manage:suppressions scope, so an API key gets 403 insufficient_scope. Use the dashboard. Members and above can add and remove entries; viewers see no buttons. See Authentication.

1. Open the Blocklist page.
2. Select Add suppression.
3. Enter the Email address and select Add suppression.

The email is trimmed and lowercased before storing. A new entry returns 201, and adding an address that is already suppressed returns 200 with the existing entry. See Create suppression for the endpoint.

Remove a suppression

1. Open the Blocklist page and select the address.
2. Select Remove on its suppression entry, then confirm with Remove.

A marketing opt-out on the Blocklist page shows Permanent and can't be removed. See Delete suppression for the endpoint.

Reason values