Suppressions

The suppression list is your account’s registry of email addresses that must not be mailed. It is checked on every send, independently of lists, segments and contact records: a suppressed address can still be a member of a list, and a suppression entry can exist for an address that has no contact at all (for example, one you blocked manually or one that remains after a GDPR erasure). Addresses are stored in lower case and matched without regard to case.

Key fields

Field Description
id The entry identifier, used by DELETE /suppressions/{id}.
email The suppressed address, lower-cased.
reason Why the address is suppressed. See Reasons.
created_at When the entry was added.

Reasons

Reason How the entry is created
unsubscribe The recipient used the unsubscribe link of a marketing message. Opening the link shows a confirmation page; the entry is written when the recipient confirms, or when their mail client performs a one-click unsubscribe. The contact, if there is one, becomes unsubscribed and a contact.unsubscribed webhook is sent.
bounce The mail provider reported a hard (permanent) bounce for a message to this address, or the address collected 5 soft bounces within 14 days. Only soft bounces that point to a problem with the recipient’s mailbox, such as a full mailbox, count towards that threshold; delays and expirations on the provider’s side do not. A single soft bounce sets the message to bounced without suppressing the address.
complaint The recipient reported one of your messages as spam through their mailbox provider.
manual You blocked the address yourself with POST /suppressions.

unsubscribe, bounce and complaint entries are written by the platform; POST /suppressions requires a reason and accepts any of the four. POST /contacts/{id}/erase also adds an entry for the erased address, so it can never be mailed or imported again — see Contacts & Audiences.

What suppression blocks

Message class unsubscribe bounce complaint manual
marketing (campaigns, automations) blocked blocked blocked blocked
transactional, critical (OTP) sent blocked blocked blocked
  • Campaigns remove suppressed addresses from the audience when it is resolved at launch, and every message is checked again just before hand-off.
  • POST /transactional/send is stricter than the table: it refuses any suppressed recipient, whatever the reason, with 403 and details.code: recipient_suppressed. POST /transactional/send-batch reports the same code for that item and sends the rest.
  • OTP and automation sends create the message and check it just before hand-off; a blocked message ends in status suppressed (see Messages) and its credit is refunded.
  • Contact imports skip rows whose address is suppressed and count them in skipped_suppressed.
  • Adding a suppressed contact to a list is allowed; the address is simply skipped whenever that list is sent to.

Lifecycle

An entry is created by one of the reasons above and stays until you delete it; entries do not expire.

(unsubscribe / hard bounce / 5 soft bounces in 14 days / complaint / POST /suppressions / erasure)
        │
        ▼
   suppressed ──DELETE /suppressions/{id}──► removed
  • POST /suppressions adds an entry with the email and the required reason you pass. An address that is already suppressed returns 409 with details.code: suppression_exists.
  • GET /suppressions is cursor-paginated (per_page and cursor).
  • DELETE /suppressions/{id} removes the entry, and sends to the address stop being blocked by it. Removing an entry does not change the contact: an unsubscribed contact stays unsubscribed and is still left out of campaigns and automations. Remove bounce and complaint entries deliberately — the underlying problem may repeat and the address may be suppressed again.
  • Suppressions tag — GET /suppressions, POST /suppressions, DELETE /suppressions/{id}.
  • Contacts tag — POST /contacts/{id}/erase, DELETE /contacts/{id}, GET /contacts/{id}/export.

See the API Reference for full schemas, Messages for how a suppressed send appears in delivery status, and Receive webhooks for the contact.unsubscribed event.