Sign inGet Started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Get an email suppression

GET
/v1/email/suppressions/{suppression_id}
const suppression = await bird.suppressions.get("sup_abc123");
console.log(suppression.reason, suppression.applies_to);
Response200
{
  "id": "sup_01krdgeqcxet5s7t44vh8rt9mg",
  "email": "user@example.com",
  "scope": {
    "type": "workspace",
    "id": "ws_01krdgeqcxet5s7t44vh8rt9mg"
  },
  "reason": "hard_bounce",
  "origin": "bounce_event",
  "applies_to": "all",
  "source_email_id": "em_01krdgeqcxet5s7t44vh8rt9mg",
  "source_recipient_id": "er_01krdgeqcxet5s7t44vh8rt9mg"
}

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.

Parameters

suppression_idstring

ID of the suppression record, as returned when the suppression was created or listed.

Response Payload

id
string
required
email
string
required

The suppressed address, stored lowercase.

scope
object
required
Show child attributes
scope.type
string
required

How widely the email suppression applies. Responses use workspace. The values category, audience, topic, contact, and domain are reserved and have no records. The record's applies_to field determines which message categories are blocked.

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

scope.id
string
required

Public ID or alias of the scoped resource. For workspace scope, this is the workspace ID.

reason
string
required

Why the address is suppressed:

  • hard_bounce: A delivery permanently failed.
  • complaint: The recipient reported a message as spam.
  • manual: Added through the API or dashboard.
  • unsubscribe: The recipient opted out. Deprecated, and no new record carries it: an opt-out is a messaging preference rather than a suppression. Legacy records remain visible until they are moved to messaging preferences.

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, manual, unsubscribe

origin
string
required

How the suppression came to exist:

  • bounce_event: Created automatically from a hard bounce.
  • complaint_event: Created from a spam complaint.
  • api_key: Added through the API with an API key.
  • user: Added by a user in the dashboard.
  • unsubscribe_event: The mailbox provider reported an opt-out. Deprecated with reason: unsubscribe.
  • unsubscribe_link: The recipient used a Bird unsubscribe link. Deprecated with reason: unsubscribe.

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, api_key, user, unsubscribe_event, unsubscribe_link

applies_to
string
required

Which sends the suppression blocks.

  • all: blocks every message category, including transactional.
  • non_transactional: blocks marketing but allows transactional messages. A recipient who complained can therefore still receive mail such as 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
required

When the address was suppressed.

Related resources

Continue with the documentation, guides and examples for this topic.

Get an implementation brief