List suppressions

Suppression lists hold recipients wemail won't send to.

Suppression lists hold recipients wemail won't send to. The system maintains them automatically — you can also add or remove entries via the API. This endpoint pages through one list by type.

GET /v3/suppressions/{type}

Retention & limits

Suppression entries are kept indefinitely — they are the record that keeps you compliant, so the data-retention sweep never touches them and there is no size cap on a list. Entries carry a source: manual (added via API/console), import (CSV import or provider migration — excluded from deliverability analytics so a migrated list can’t distort your rates), delivery_report (added automatically from a hard bounce or complaint) and verification (added by the email-verification engine).

Query parameters

Parameter	Type	Required	Description
`page`	integer	Optional	Page number, starting at 1. Default 1.
`per_page`	integer	Optional	Entries per page, 1–100. Default 25.
`search`	string	Optional	Filter entries by email address (max 200 chars).
`since`	ISO-8601	Optional	Only entries created at or after this instant. Preferred — consistent with `GET /events`.
`until`	ISO-8601	Optional	Only entries created at or before this instant. Preferred — consistent with `GET /events`.
`from_date`	date (YYYY-MM-DD)	Optional	Deprecated — use `since`. UTC calendar-day lower bound on created_at.
`to_date`	date (YYYY-MM-DD)	Optional	Deprecated — use `until`. UTC calendar-day upper bound, inclusive to end-of-day.
`from`	epoch milliseconds	Optional	Deprecated — use `since`. Epoch-ms lower bound on created_at.
`to`	epoch milliseconds	Optional	Deprecated — use `until`. Epoch-ms upper bound on created_at.

Filter the list by creation time with `since` and `until` — ISO 8601 date-time instants, exactly like GET /events. The older from/to (epoch milliseconds) and from_date/to_date (calendar day) params still work but are deprecated; prefer since/until. If more than one time filter is supplied, precedence is since/until → from/to → from_date/to_date.

Types

Parameter	Type	Required	Description
`bounces`	hard-bounce list	Optional	Permanent failures: invalid mailboxes, banned domains.
`unsubscribes`	opt-out list	Optional	One-click and link-based unsubscribes.
`complaints`	spam-complaint list	Optional	Recipients who marked your messages as spam.
`allowlist`	always-deliver list	Optional	Exceptions, not blocks: allowlisted addresses are never auto-suppressed and are delivered even if they carry bounce or spam-complaint entries. An unsubscribe still wins unless the entry was created with `override_unsubscribes: true`. Useful for QA inboxes you own.

How suppression works

wemail owns your suppression list end-to-end — it is the single source of truth that gates every send. Entries are added automatically from: hard bounces and spam complaints (captured from delivery events), one-click unsubscribes (the RFC 8058 List-Unsubscribe header), and any manual entries you add via the API or Console. The allowlist works the other way around: an allowlisted address is exempt from automatic suppression and from bounce/complaint blocks — and, only if you explicitly set override_unsubscribes, from unsubscribes too. The platform-wide invalid-address shield is never overridden.

Sending to a suppressed address

The API still accepts the request and returns 202 — suppression is not checked at submit time. At delivery, wemail sees the recipient on your list, skips the send entirely (the upstream provider is never contacted), records a rejected event with data.reason: "all_recipients_suppressed", and fires a rejected webhook. If only some recipients of a message are suppressed, just those are dropped and the rest are delivered normally.

Responses

Status	Description
`200`	OK. A page of suppression entries of this type (`id`, `type`, `email`, `reason`, `source`, `override_unsubscribes`, `created_at`), oldest first.
`400`	Invalid suppression type or query parameters.
`401`	Missing or invalid API key.

Code examples

cURL

curl -G https://api.wemail.io/v3/suppressions/bounces \
  -H "Authorization: Bearer afn_live_…" \
  --data-urlencode "since=2026-05-01T00:00:00Z" \
  --data-urlencode "until=2026-06-01T00:00:00Z"

Node.js

const bounces = await wemail.suppressions.list("bounces");

Python

bounces = wemail.suppressions.list("bounces")

PHP

$bounces = $wemail->suppressions->list('bounces');

Ruby

bounces = wemail.suppressions.list("bounces")

bounces, _ := client.ListSuppressions("bounces")

Java

wemail.listSuppressions("bounces");

.NET

var bounces = await wemail.ListSuppressionsAsync("bounces");