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