Get a suppression
GET
/v1/email/suppressions/{suppression_id}
curl -X GET "https://us1.platform.bird.com/v1/email/suppressions/{suppression_id}" \
-H "Authorization: Bearer $TOKEN"Returns one suppression record:
- The address.
- Why it is suppressed (reason).
- How the record came to exist (origin).
- Which message categories it blocks (applies_to).
To find a record when you only know the address, use GET /v1/email/suppressions with the email parameter. An ID that does not exist in the workspace returns 404.
Payload di risposta
id
string
obbligatorio
email
string
obbligatorio
The suppressed address, stored lowercase.
scope
object
obbligatorio
Mostra attributi secondari
scope.type
string
obbligatorio
How wide this suppression reaches. It is always workspace, which
means the address is blocked for every email your workspace sends.
The id beside it is then your workspace ID.
This only affects email. Your WhatsApp suppressions are a separate
list, and blocking an address here does nothing to them.
The enum lists five narrower values as well: category, audience,
topic, contact and domain. You will never get one of them back,
because every suppression is workspace-wide. If you are writing code,
you can treat this field as always reading workspace.
Possible values: workspace, category, audience, topic, contact, domain
scope.id
string
obbligatorio
Public ID or alias of the scoped resource. For workspace scope, this is the workspace ID (ws_-prefixed).
reason
string
obbligatorio
Why the address is suppressed:
- hard_bounce: A delivery permanently failed.
- complaint: The recipient reported a message as spam.
- unsubscribe: The recipient opted out.
- 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.
Possible values (may grow over time): hard_bounce, complaint, unsubscribe, manual
origin
string
obbligatorio
How the suppression came to exist:
- bounce_event: Created automatically from a hard bounce.
- complaint_event: Created from a spam complaint.
- unsubscribe_event: Created 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.
- user: Added by a user in the dashboard.
This list grows over time. Treat unknown values as informational rather than rejecting the record.
Possible values (may grow over time): bounce_event, complaint_event, unsubscribe_event, unsubscribe_link, api_key, user
applies_to
string
obbligatorio
Which sends the suppression blocks. all blocks every message category, including transactional. non_transactional blocks marketing but allows transactional, so a recipient who complained or unsubscribed can still receive mail like password resets. category scopes the block to a preference category and blocks every category until one is set. This list grows over time, and any value other than non_transactional blocks every category, so treat an unknown value as blocking the send.
Possible values (may grow over time): all, non_transactional, category
source_email_id
nullable string
ID of the email that triggered suppression. Null for manual additions.
source_recipient_id
nullable string
ID of the recipient event that triggered suppression. Null for manual additions.
created_at
string
obbligatorio
When the address was suppressed.