Create an email suppression
/v1/email/suppressions// Adding is idempotent: an existing `manual` record is returned unchanged.
const suppression = await bird.suppressions.add({
email: "blocked@example.com",
});
console.log(suppression.id);# Adding is idempotent, so an address that already carries a manual
# suppression returns the existing record.
suppression = client.suppressions.add(email="blocked@example.com")
print(suppression.id)// Adding is idempotent: an address already suppressed manually returns that record.
suppression, err := client.Suppressions.Add(context.Background(), bird.SuppressionsAddParams{
Email: "blocked@example.com",
})
if err != nil {
log.Fatal(err)
}
fmt.Println(suppression.Id)// Adding is idempotent: an address with a manual suppression returns that record.
$suppression = $bird->suppressions->add(
(new SuppressionCreate())->setEmail('blocked@example.com'),
);
echo $suppression->getId();bird email suppressions add --email jane@example.comcurl -X POST "https://us1.platform.bird.com/v1/email/suppressions" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"email": "jane@example.com"
}'{
"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.
Request Payload
emailThe address to stop sending to. Normalized before storage and matching: lowercased and trimmed of surrounding whitespace.
Response Payload
idemailThe suppressed address, stored lowercase.
scopeShow child attributes
scope.typeHow 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.idPublic ID or alias of the scoped resource. For workspace scope, this is the workspace ID.
reasonWhy 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
originHow 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 withreason: unsubscribe.unsubscribe_link: The recipient used a Bird unsubscribe link. Deprecated withreason: 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_toWhich 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_idID of the email that triggered suppression. Null for manual additions.
source_recipient_idID of the recipient event that triggered suppression. Null for manual additions.
created_atWhen the address was suppressed.
Related resources
Continue with the documentation, guides and examples for this topic.