Suppression List
Manage your suppression list - a list of recipient email addresses to which you do NOT want to send email.
A suppression list, also known as an exclusion list, stores a recipient's opt-out preferences. It is a list of recipient email addresses to which you do NOT want to send email. Each entry indicates whether the recipient opted out of receiving one of the following:
Transactional messages - single recipient messages that are used operationally, e.g. to reset a password or confirm a purchase.
Non-transactional messages - used to run email campaigns where a list of recipients are targeted, e.g. advertising a sales event.
When setting up your account, we strongly recommend you import any suppression list you have from any previous service to avoid incorrectly sending mail to unsubscribed/invalid recipients.
Recipient Maintenance
It's good practice to maintain your recipient lists by removing recipients based on the bounce, unsubscribe, and spam complaint events provided by the service. These events are available from webhooks and message events.
The service supports bulk importing or manually adding up to 1,000,000 suppression list entries total.
Each workspace has its own independent suppression list.
Perform a filtered search for entries in your suppression list. Returns an array of suppression objects.
The ID of the workspace
Date the suppressions were last updated, in the format of YYYY-MM-DDTHH:mm:ssZ
now
Date the suppressions were last updated, in the format YYYY-MM-DDTHH:mm:ssZ
Domains to match in the search
Sources to match in the search, i.e. entries that were added by this source
Types of suppressions to match in the search
String to match in suppression descriptions
When set to true, will match the exact content in the search description
false
The results cursor location to return
Maximum number of results to return per page (1-10000)
1000
The results page number to return
Sort by updated field
desc
Possible values: Successfully retrieved suppressions
GET /api/workspaces/{workspaceId}/reach/suppression-list HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
Successfully retrieved suppressions
{
"results": [
{
"recipient": "[email protected]",
"source": "Bounce Rule",
"type": "transactional",
"created": "2017-02-01T01:01:01+00:00",
"updated": "2017-02-01T01:01:01+00:00",
"transactional": true
},
{
"recipient": "[email protected]",
"description": "550: this email address does not exist #55",
"source": "Manually Added",
"type": "transactional",
"created": "2018-01-01T01:01:01+00:00",
"updated": "2018-01-01T01:01:01+00:00",
"non_transactional": true
}
],
"links": [],
"total_count": 2
}
Bulk create or update entries in the suppression list.
If a recipient was added by our compliance system, it cannot be updated.
Please note that in the unlikely scenario where your receive a HTTP 5xx level error response while bulk loading, only some of your suppression entries may have been successfully created or updated. If this occurs, please re-submit your original request again for processing.
The ID of the workspace
Successfully updated suppression list
Bad Request
PUT /api/workspaces/{workspaceId}/reach/suppression-list HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 284
{
"recipients": [
{
"recipient": "[email protected]",
"type": "transactional",
"description": "User requested to not receive any transactional emails."
},
{
"recipient": "[email protected]",
"type": "non_transactional",
"description": "User requested to not receive any non-transactional emails."
}
]
}
{
"results": {
"message": "Suppression List successfully updated"
}
}
Return all suppression entries for a recipient. If the recipient is not in the suppression list, an HTTP status of 404 is returned.
Searches across multiple lists can return out of date results, with a delay of up to 20 minutes. Searches against a specific list are not affected by this delay and return up-to-date information.
The ID of the workspace
Recipient email address
Types of suppressions to match in the search
The results cursor location to return
Maximum number of results to return per page (1-10000)
1000
The results page number to return
Successfully retrieved suppression
Recipient not found
GET /api/workspaces/{workspaceId}/reach/suppression-list/{recipient} HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
{
"results": [
{
"recipient": "[email protected]",
"non_transactional": true,
"type": "non_transactional",
"source": "Manually Added",
"description": "User requested to not receive any non-transactional emails.",
"created": "2015-01-01T12:00:00+00:00",
"updated": "2015-01-01T12:00:00+00:00"
}
],
"links": [],
"total_count": 1
}
Create or update a suppression entry. If the recipient was added by our compliance system, it cannot be updated.
The ID of the workspace
Recipient email address
Type of suppression record.
Explanation for the suppression.
Successfully updated suppression
Bad Request
PUT /api/workspaces/{workspaceId}/reach/suppression-list/{recipient} HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 68
{
"type": "transactional",
"description": "Unsubscribe from newsletter"
}
{
"results": {
"message": "Suppression list successfully updated"
}
}
Delete a suppression entry for a recipient.
The ID of the workspace
Recipient email address
The type of suppression to delete. If not provided, the suppression will be deleted for both transactional and non-transactional.
Successfully deleted suppression
Forbidden
Recipient not found
DELETE /api/workspaces/{workspaceId}/reach/suppression-list/{recipient} HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 24
{
"type": "transactional"
}
No content
Returns the total number of suppressions for your account, as well as a break down of suppressions by source.
The ID of the workspace
Successfully retrieved summary
GET /api/workspaces/{workspaceId}/reach/suppression-list/summary HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
Successfully retrieved summary
{
"results": {
"compliance": 1,
"manually_added": 1542,
"unsubscribe_link": 1,
"bounce_rule": 3891,
"list_unsubscribe": 1,
"spam_complaint": 1,
"total": 5437
}
}
Was this helpful?