Suppression List

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 SparkPost 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 SparkPost. These events are available from webhooks and message events.

SparkPost supports bulk importing or manually adding up to 1,000,000 suppression list entries total.

Subaccount Suppressions

Each subaccount has it's own independent suppression list. Set the X-MSYS-SUBACCOUNT header to a subaccount ID to search and operate on that subaccount's suppression list. By default, the search endpoint will search across the primary account's and all subaccounts' lists.

Suppression Object

Example

{
  "recipient": "recip@example.com",
  "type": "non_transactional",
  "source": "List Unsubscribe",
  "description": "Unsubscribed using list unsubscribe header",
  "created": "2017-10-01T12:00:00+00:00",
  "updated": "2017-10-01T12:00:00+00:00",
  "transactional": false,
  "non_transactional": true
}

Attributes

recipient string

Email address to be suppressed.

type enum

Type of suppression record.

Possible Values: transactional, non_transactional

source enum

Source responsible for creating the list entry.

Possible Values: Spam Complaint, List Unsubscribe, Bounce Rule, Unsubscribe Link, Manually Added, Compliance

description string

Explanation for the suppression.

created string

Date suppression was created.

updated string

Last time the suppression was updated.

transactional boolean

Whether the recipient requested to not receive any transactional messages. Deprecated in favor of type.

non_transactional boolean

Whether the recipient requested to not receive any non-transactional messages. Deprecated in favor of type.

subaccount_id number

Which subaccount the recipient is suppressed for. Only returned if suppressed for a specific subaccount.

Request

PUT /api/v1/suppression-list/

{
  "recipients": [
    {
      "recipient": "rcpt_1@example.com",
      "type": "transactional",
      "description": "User requested to not receive any transactional emails."
    },
    {
      "recipient": "rcpt_2@example.com",
      "type": "non_transactional",
      "description": "User requested to not receive any non-transactional emails."
    }
  ]
}

Response

{
  "results": {
    "message": "Suppression List successfully updated"
  }
}

{
  "errors": [
    {
      "message": "PUT body contains 2 invalid or malformed recipient(s): rcpt_1@example.com, rcpt_2@example.com"
    }
  ]
}

Bulk Create or Update Suppressions

PUT/api/v1/suppression-list/

Bulk create or update entries in the suppression list.

If a recipient was added by our compliance system, it cannot be updated.

Request Body

recipients array required

Array of recipient objects to add to or updates in the suppression list. Max size: 50mb. Max length: 10,000.

Recipient Object

recipient string required

Email address to be suppressed.

type enum required

Type of suppression record.

Possible Values: transactional, non_transactional

description string

Explanation for the suppression.

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.

Request

PUT /api/v1/suppression-list/rcpt@example.com

{
  "type": "transactional",
  "description": "Unsubscribe from newsletter"
}

Response

{
  "results": {
    "message": "Suppression list successfully updated"
  }
}

{
  "errors": [
    {
      "message": "Must supply a suppression type"
    }
  ]
}

  {
      "errors": [
          {
              "message": "Type must be one of: \'transactional\', \'non_transactional\'"
          }
      ]
  }

Create or Update a Suppression

PUT/api/v1/suppression-list/{recipient}

Parameters

recipient string required

Recipient email address.

If the recipient was added by our compliance system, it cannot be updated.

Request Body

type enum required

Type of suppression record.

Possible Values: transactional, non_transactional

description string

Explanation for the suppression.

Request

GET /api/v1/suppression-list/rcpt@example.com

Response

{
  "results": [
    {
      "recipient": "rcpt@example.com",
      "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"
    },
    {
      "recipient": "rcpt@example.com",
      "non_transactional": true,
      "type": "non_transactional",
      "source": "Bounce Rule",
      "description": "550: 550 - Domain has been disabled. #7",
      "created": "2016-10-01T12:00:00+00:00",
      "updated": "2016-10-01T12:00:00+00:00",
      "subaccount_id": "146"
    }
  ],
  "links": [],
  "total_count": 2
}

Retrieve a Suppression

GET/api/v1/suppression-list/{recipient}

Parameters

recipient string required

Recipient email address.

types list

Types of suppressions to match in the search, i.e. entries that are transactional or non_transactional.

cursor string

The results cursor location to return, to start paging with cursor, use the value of 'initial'. When cursor is provided the page parameter is ignored.

per_page number, default is 1000

Maximum number of results to return per page. Must be between 1 and 10,000.

page number

The results page number to return. Used with per_page for paging through results. Works up to 10,000 results. Use the cursor parameter to page larger result sets.

Return all suppression entries for a recipient. If the recipient is not in the suppression list, an HTTP status of 404 is returned.

Searching with Subaccounts

If your account has subaccounts, please provide the X-MSYS-SUBACCOUNT header when performing a lookup on a specific suppression list.

Use a value of 0 to only search against the primary account suppression list.
Use the subaccount's ID to perform a lookup on a specific subaccount suppression list.

If the X-MSYS-SUBACCOUNT header is not provided, a search will be performed across the primary account and all subaccount suppression lists. 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. If you don't have subaccounts, you do not need to provide the X-MSYS-SUBACCOUNT header in order to receive up-to-date results.

Request

DELETE /api/v1/suppression-list/rcpt@example.com

{
  "type": "transactional"
}

Response

// Empty response body

{
  "errors": [
    {
      "message": "Recipient could not be removed - Compliance"
    }
  ]
}

{
  "errors": [
    {
      "message": "Recipient could not be found"
    }
  ]
}

Delete a Suppression

DELETE/api/v1/suppression-list/{recipient}

Parameters

recipient string required

Recipient email address.

Deleting from subaccounts

If your account has subaccounts, please provide the X-MSYS-SUBACCOUNT header when deleting from a specific subaccount suppression list.

Omit the header to delete from the primary account suppression list.
Use the subaccount's ID to delete from a specific subaccount suppression list.

Request Body

type enum

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

Possible Values: transactional, non_transactional

Request

GET /api/v1/suppression-list?from=2017-01-01T09:00:00-0400&domain=example.com&sources=Bounce%20RuleManually%20Added&types=transactional

Response

{
  "results": [
    {
      "recipient": "test@example.com",
      "source": "Bounce Rule",
      "type": "transactional",
      "created": "2017-02-01T01:01:01+00:00",
      "updated": "2017-02-01T01:01:01+00:00",
      "transactional": true
    },
    {
      "recipient": "test2@example.com",
      "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
    },
    {
      "recipient": "test3@example.com",
      "description": "Recipient unsubscribed",
      "source": "Bounce Rule",
      "type": "transactional",
      "created": "2018-01-01T01:01:01+00:00",
      "updated": "2018-01-01T01:01:01+00:00",
      "transactional": true
    }
  ],
  "links": [],
  "total_count": 3
}

Search Suppressions

GET/api/v1/suppression-list{?to,from,domain,sources,types,description,description_strict,cursor,per_page,page,sort}

Parameters

to string, default is now

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

from string

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

domain string

Domains to match in the search.

sources list

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

types list

Types of suppressions to match in the search, i.e. entries that are transactional or non_transactional.

description string

String to match in suppression descriptions.

description_strict boolean, default is false

A complementary field to description. When set to true, will match the exact content in the search description, alternatively will fetch all combination of results in the description.

cursor string

The results cursor location to return, to start paging with cursor, use the value of 'initial'. When cursor is provided the page parameter is ignored.

per_page number, default is 1000

Maximum number of results to return per page. Must be between 1 and 10,000.

page number

The results page number to return. Used with per_page for paging through results. Works up to 10,000 results. Use the cursor parameter to page larger result sets.

sort enum, default is desc

Sort will return results sorted by the updated field in ascending (asc) or descending (desc) order.

Possible Values: asc, desc

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

Request

GET /api/v1/suppression-list/summary

Response

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

Retrieve Summary

GET/api/v1/suppression-list/summary

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