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.

Regional Endpoints

Please use the appropriate API endpoint based on your workspace region:

• EU workspaces: https://email.eu-west-1.api.bird.com

• US workspaces: https://email.us-west-2.api.bird.com

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.

Search Suppressions

get

https://email.eu-west-1.api.bird.com/apihttps://email.us-west-2.api.bird.com/api

/workspaces/{workspaceId}/reach/suppression-list

Perform a filtered search for entries in your suppression list. Returns an array of suppression objects.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

tostring · date-timeOptional

Date the suppressions were last updated, in the format of YYYY-MM-DDTHH:mm:ssZ

Default: now

fromstring · date-timeOptional

Date the suppressions were last updated, in the format YYYY-MM-DDTHH:mm:ssZ

domainstringOptional

Domains to match in the search

sourcesstringOptional

Sources to match in the search, i.e. entries that were added by this source

typesstringOptional

Types of suppressions to match in the search

descriptionstringOptional

String to match in suppression descriptions

description_strictbooleanOptional

When set to true, will match the exact content in the search description

Default: false

cursorstringOptional

The results cursor location to return

per_pageinteger · min: 1 · max: 10000Optional

Maximum number of results to return per page (1-10000)

Default: 1000

pageintegerOptional

The results page number to return

sortstring · enumOptional

Sort by updated field

Default: descPossible values:

Responses

200

Successfully retrieved suppressions

application/json

get

/workspaces/{workspaceId}/reach/suppression-list

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/suppression-list HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

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 Suppressions

put

https://email.eu-west-1.api.bird.com/apihttps://email.us-west-2.api.bird.com/api

/workspaces/{workspaceId}/reach/suppression-list

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.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Body

application/json

Responses

200

Successfully updated suppression list

application/json

400

Bad Request

application/json

put

/workspaces/{workspaceId}/reach/suppression-list

HTTPcURLJavaScriptPython

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"
  }
}

Retrieve a Suppression

get

https://email.eu-west-1.api.bird.com/apihttps://email.us-west-2.api.bird.com/api

/workspaces/{workspaceId}/reach/suppression-list/{recipient}

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.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

recipientstringRequired

Recipient email address

Query parameters

typesstringOptional

Types of suppressions to match in the search

cursorstringOptional

The results cursor location to return

per_pageinteger · min: 1 · max: 10000Optional

Maximum number of results to return per page (1-10000)

Default: 1000

pageintegerOptional

The results page number to return

Responses

200

Successfully retrieved suppression

application/json

404

Recipient not found

application/json

get

/workspaces/{workspaceId}/reach/suppression-list/{recipient}

HTTPcURLJavaScriptPython

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

put

https://email.eu-west-1.api.bird.com/apihttps://email.us-west-2.api.bird.com/api

/workspaces/{workspaceId}/reach/suppression-list/{recipient}

Create or update a suppression entry. If the recipient was added by our compliance system, it cannot be updated.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

recipientstringRequired

Recipient email address

Body

application/json

typestring · enumRequired

Type of suppression record.

Possible values:

descriptionstringOptional

Explanation for the suppression.

Responses

200

Successfully updated suppression

application/json

400

Bad Request

application/json

put

/workspaces/{workspaceId}/reach/suppression-list/{recipient}

HTTPcURLJavaScriptPython

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

delete

https://email.eu-west-1.api.bird.com/apihttps://email.us-west-2.api.bird.com/api

/workspaces/{workspaceId}/reach/suppression-list/{recipient}

Delete a suppression entry for a recipient.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

recipientstringRequired

Recipient email address

Body

application/json

typestring · enumOptional

The type of suppression to delete. If not provided, the suppression will be deleted for both transactional and non-transactional.

Possible values:

Responses

204

Successfully deleted suppression

403

Forbidden

application/json

404

Recipient not found

application/json

delete

/workspaces/{workspaceId}/reach/suppression-list/{recipient}

HTTPcURLJavaScriptPython

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

Retrieve Summary

get

https://email.eu-west-1.api.bird.com/apihttps://email.us-west-2.api.bird.com/api

/workspaces/{workspaceId}/reach/suppression-list/summary

Returns the total number of suppressions for your account, as well as a break down of suppressions by source.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Responses

200

Successfully retrieved summary

application/json

get

/workspaces/{workspaceId}/reach/suppression-list/summary

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/suppression-list/summary HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved summary

{
  "results": {
    "compliance": 1,
    "manually_added": 1542,
    "unsubscribe_link": 1,
    "bounce_rule": 3891,
    "list_unsubscribe": 1,
    "spam_complaint": 1,
    "total": 5437
  }
}