Dokumentation
Sign inGet started
Jetzt starten
Anleitungen
API-Referenz
SDKs
CLI
Wissensdatenbank
Changelog

Create a suppression

POST
/v1/email/suppressions
curl -X POST "https://us1.platform.bird.com/v1/email/suppressions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com"
  }'
Antwort200
{
  "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"
}
Adds an email address to the suppression list, stopping all email to it. The record is created with reason manual and blocks every message category, including transactional.
Adding is idempotent: a 201 means a new record was created, and a 200 means a manual suppression for the address already existed and is returned unchanged. An address suppressed for another reason (for example hard_bounce) gets a separate manual record, and delivery stays blocked until every blocking record is removed.
Anfrage-Nutzlast
email
string
erforderlich
The address to stop sending to. Normalized before storage and matching: lowercased and trimmed of surrounding whitespace.
Antwort-Payload
id
string
erforderlich
email
string
erforderlich
The suppressed address, stored lowercase.
scope
object
erforderlich
Untergeordnete Attribute anzeigen
scope.type
string
erforderlich
How widely the email suppression applies. Responses currently use workspace, which blocks the address for every email sent by the workspace. WhatsApp suppressions use a separate list.
Possible values: workspace, category, audience, topic, contact, domain
scope.id
string
erforderlich
Public ID or alias of the scoped resource. For workspace scope, this is the workspace ID.
reason
string
erforderlich
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.
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
origin
string
erforderlich
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.
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
applies_to
string
erforderlich
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
erforderlich
When the address was suppressed.