Suppressions

The suppression list is the mechanism that protects your sending reputation. Any address that generates a permanent bounce, a spam complaint, or unsubscribes is added to the list automatically, and the platform skips that email on all future sends — both transactional and bulk — without you having to do anything.

How entries are added

Suppressions are created in three ways:

Source	`reason`	Description
Permanent bounce (5xx)	`bounce`	The receiving server permanently rejected the address
FBL / spam complaint	`complaint`	The recipient marked the email as spam
Unsubscribe	`unsubscribed`	The contact clicked the unsubscribe link or called the unsubscribe endpoint
Manual	`manual`	An admin added the address manually via API or dashboard

Operations

GET /v1/suppressions — list all suppressed addresses, paginated. Query params: limit (default 100, max 1000), offset, reason (bounce|complaint|manual), email (partial search).
POST /v1/suppressions — manually add an address (requires admin key). Body: { email: string, reason?: "manual"|"complaint" }. Useful for importing your own opt-out lists.
DELETE /v1/suppressions/{email} — “remove” a suppression so the address can receive emails again (requires admin key). Returns 204.

Example: list recent suppressions

# List the last 20 bounce suppressions
curl "https://api.mailerdash.com/v1/suppressions?reason=bounce&limit=20" \
  -H "Authorization: Bearer $MAILERDASH_API_KEY"

Response:

{
  "total": 47,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "email": "usuario@dominio.com",
      "reason": "bounce",
      "code": "5.1.1",
      "added_at": "2026-06-15T10:30:00.000Z"
    }
  ]
}

Example: add a manual suppression

curl -X POST https://api.mailerdash.com/v1/suppressions \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "optout@cliente.com", "reason": "manual"}'

Example: remove a suppression

curl -X DELETE "https://api.mailerdash.com/v1/suppressions/usuario%40dominio.com" \
  -H "Authorization: Bearer $MAILERDASH_API_KEY"

If a user exercises their right to data erasure (right to be forgotten), the correct process in MailerDash is:

Delete the contact via DELETE /v1/bulk/contacts/{email} — this removes them from your lists.
Do not remove the suppression — keeping it protects the user from receiving accidental future emails.

The user’s account on the platform (if one exists) is anonymized (email/name replaced with placeholders) when deleted, but suppressions remain as protection, not as personally identifiable data.

API reference: Platform — Suppressions

Migrating your list from another provider

If you’re coming from another ESP, upload their suppression list before your first campaign. It isn’t paperwork: that list holds addresses that already bounced or already marked you as spam over there. Without importing it, your first send with us writes to all of them again and collects the same bounces and the same complaints — with the reputation cost that carries, for you and for the rest of the platform.

It’s under Deliverability → Suppressions → Import CSV, either uploading the file or pasting the addresses. The parser accepts the common headers (email, address) and also a single-column file with no header at all.

Pick the list type carefully

It’s the only decision in the form, and the options differ:

Type	What it blocks
Marketing unsubscribes (default)	Campaigns and sequences only. They still get your transactional mail — receipts, password resets.
Bounces · Spam complaints · Manual block	All mail, transactional included.

The default is the least destructive on purpose. Another provider’s export is mostly marketing unsubscribes, and importing those as a full block would leave those people unable to reset their password — locked out of their own account for having said they didn’t want promotions.

If your file has a reason column with one of those values, it’s honored row by row and the selected type applies only to the rest.

Re-importing is safe

Addresses already suppressed are skipped: no duplicates, no double counting. The response tells you how many went in, how many were already there, and which weren’t valid addresses.

Exporting

The Export button downloads your full list as CSV with email, reason and added_at — the same columns the import accepts, so the file that comes out goes back in. Useful as a backup and for personal-data requests.