Suppression List

Manage email addresses that are blocked from receiving emails. Addresses are automatically suppressed on hard bounces, spam complaints, and after 3 consecutive soft bounces. Manual entries can also be added via API or dashboard.

The suppression list prevents sending to email addresses that have previously hard-bounced, soft-bounced repeatedly, or received spam complaints. This protects your sender reputation and improves deliverability.

Automatic suppression:

Permanent bounces — when SES reports a permanent (hard) bounce, all bounced recipient addresses are added with reason "hard_bounce"
Spam complaints — when a recipient marks your email as spam, their address is added with reason "complaint"
Repeated soft bounces — after 3 consecutive soft bounces (Transient or Undetermined SES bounce types) from the same address with no successful delivery in between, the address is added with reason "soft_bounce". The counter resets on any successful delivery, so transient mailbox issues don't accumulate forever.

Reason codes:

hard_bounce — permanent failure (mailbox doesn't exist, domain unreachable)
soft_bounce — 3+ consecutive transient failures (mailbox full, server temporarily down)
complaint — recipient reported the email as spam
manual — added manually by you (via API or dashboard)

Send behavior:

Before every send (API and SMTP), suppressed recipients are silently filtered out
If ALL recipients in a request are suppressed, the send fails with an error message listing the suppressed addresses
CC and BCC recipients are also checked and filtered
Newsletter and broadcast sends share the same suppression list

Manual management:

Add addresses manually via the dashboard or API with reason "manual"
Remove any suppression (auto or manual) to allow sending again — the soft bounce counter is also wiped
Each suppression is scoped to your workspace — other workspaces are not affected

GET/v1/suppressions

List all suppressed email addresses in the current workspace, ordered by most recently added.

Authorizations

Authorizationstring · headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your API Key.

GET /v1/suppressions

curl https://api.posthawk.dev/v1/suppressions \
  -H "Authorization: Bearer your_api_key"

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "bounced@example.com",
    "reason": "hard_bounce",
    "notes": "smtp; 550 5.1.1 The email account does not exist",
    "created_at": "2026-04-15T10:30:00.000Z"
  },
  {
    "id": "7d24c920-a8eb-22e2-91c5-11d15ec541d9",
    "email": "fullmailbox@example.com",
    "reason": "soft_bounce",
    "notes": "3 consecutive soft bounces — last: 452 4.2.2 Mailbox full",
    "created_at": "2026-04-14T14:22:00.000Z"
  },
  {
    "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "email": "complained@example.com",
    "reason": "complaint",
    "notes": "abuse",
    "created_at": "2026-04-14T08:15:00.000Z"
  }
]

POST/v1/suppressions

Manually add an email address to the suppression list. Idempotent — adding an already-suppressed address is a no-op.

Authorizations

Authorizationstring · headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your API Key.

Body

emailstringrequired

Email address to suppress (will be lowercased)

notesstringoptional

Optional note explaining why the address was suppressed

POST /v1/suppressions

curl -X POST https://api.posthawk.dev/v1/suppressions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -d '{
    "email": "user@example.com",
    "notes": "Requested removal from mailing list"
  }'

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "reason": "manual",
  "notes": "Requested removal from mailing list",
  "created_at": "2025-06-15T10:30:00.000Z"
}

DELETE/v1/suppressions/:id

Remove a suppression entry, allowing the email address to receive emails again.

Authorizations

Authorizationstring · headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your API Key.

Path Parameters

idstringrequired

Suppression entry UUID

DELETE /v1/suppressions/:id

curl -X DELETE https://api.posthawk.dev/v1/suppressions/{id} \
  -H "Authorization: Bearer your_api_key"

Response

{
  "success": true
}

SMTP Relay

Sandbox Mode