<Intro>

<EndpointHeader />

<Description>

Returns the workspace's suppressed email addresses as a paginated list, newest first. Pass a full address in the `email` parameter to look up a single address before sending to it.

An address can appear more than once: Bird keeps one suppression record per reason, and delivery stays blocked while any blocking record for the address remains.

</Description>

</Intro>

<Parameters in="query">

<Parameter name="email" type="string">

<Description>

Case-insensitive prefix filter on the address: returns every suppression whose address starts with this value, so a full address finds that address's records and a fragment such as `alice` finds every address beginning with it. The same address can match several records, one per suppression reason.

</Description>

</Parameter>

<Parameter name="reason" type="string">

<Description>

Return only suppressions with this reason: `hard_bounce` (delivery permanently failed), `complaint` (the recipient reported a message as spam), `unsubscribe` (the recipient opted out), or `manual` (added through the API or dashboard).

</Description>

</Parameter>

<Parameter name="scope_type" type="string">

<Description>

Filter by scope type. Suppressions are currently always workspace-scoped; the other values are reserved for future use.

</Description>

</Parameter>

<Parameter name="limit" type="integer">

<Description>

Maximum number of items to return per page.

</Description>

</Parameter>

<Parameter name="starting_after" type="string">

<Description>

Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.

</Description>

</Parameter>

<Parameter name="ending_before" type="string">

<Description>

Cursor from the `prev_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order.

</Description>

</Parameter>

</Parameters>

<Payload kind="response">

<Field name="data" type="array of object" required>

<Description>

Page of suppression records.

</Description>

<FieldChildren kind="response">

<Field name="id" type="string" prefix="data." required />

<Field name="email" type="string" prefix="data." required>

<Description>

The suppressed address, stored lowercase.

</Description>

</Field>

<Field name="scope" type="object" prefix="data." required>

<FieldChildren kind="response">

<Field name="type" type="string" prefix="data.scope." required>

<Description>

The scope this suppression applies to. Suppressions are currently workspace-scoped; the other scope types are reserved for future use.

</Description>

<Description>

Possible values: `workspace`, `category`, `audience`, `topic`, `contact`, `domain`

</Description>

</Field>

<Field name="id" type="string" prefix="data.scope." required>

<Description>

Public ID or alias of the scoped resource. For workspace scope, this is the workspace ID (`ws_`-prefixed).

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="reason" type="string" prefix="data." required>

<Description>

Why the address is suppressed: `hard_bounce` (a delivery permanently failed), `complaint` (the recipient reported a message as spam), `unsubscribe` (the recipient opted out), or `manual` (added through the API or dashboard). An address can hold one record per reason. This list grows over time; treat unknown values as informational rather than rejecting the record.

</Description>

<Description>

Possible values (may grow over time): `hard_bounce`, `complaint`, `unsubscribe`, `manual`

</Description>

</Field>

<Field name="origin" type="string" prefix="data." required>

<Description>

How the suppression came to exist: `bounce_event` (created automatically from a hard bounce), `complaint_event` (from a spam complaint), `unsubscribe_event` (from an unsubscribe reported for a message, such as the recipient's mail client's unsubscribe action), `unsubscribe_link` (the recipient opted out through the unsubscribe page linked from a message), `api_key` (added through the API with an API key), or `user` (added by a user in the dashboard). This list grows over time; treat unknown values as informational rather than rejecting the record.

</Description>

<Description>

Possible values (may grow over time): `bounce_event`, `complaint_event`, `unsubscribe_event`, `unsubscribe_link`, `api_key`, `user`

</Description>

</Field>

<Field name="applies_to" type="string" prefix="data." required>

<Description>

Which sends the suppression blocks. `all` blocks every message category, including transactional. `non_transactional` blocks marketing and future non-transactional categories but allows transactional, so a recipient who complained or unsubscribed can still receive mail like password resets. `category` is reserved for category-specific preferences. This list grows over time; treat an unknown value as blocking at least non-transactional mail.

</Description>

<Description>

Possible values (may grow over time): `all`, `non_transactional`, `category`

</Description>

</Field>

<Field name="source_email_id" type="nullable string" prefix="data.">

<Description>

ID of the email that triggered suppression. Null for manual additions.

</Description>

</Field>

<Field name="source_recipient_id" type="nullable string" prefix="data.">

<Description>

ID of the recipient event that triggered suppression. Null for manual additions.

</Description>

</Field>

<Field name="created_at" type="string" prefix="data." required>

<Description>

When the address was suppressed.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="next_cursor" type="nullable string" required>

<Description>

Cursor for the next page. Pass back as `starting_after` to advance forward. Null when no next page exists.

</Description>

</Field>

<Field name="prev_cursor" type="nullable string" required>

<Description>

Cursor for the previous page. Pass back as `ending_before` to step backward. Null when no previous page exists.

</Description>

</Field>

<Field name="refresh_cursor" type="nullable string" required>

<Description>

Refresh anchor. Pass back as `ending_before` later to fetch items that have appeared since this response. Non-null whenever `data` is non-empty; null only on an empty page. Distinct from `prev_cursor`.

</Description>

</Field>

</Payload>