Suppression List API Updates Gears Laptop

New Suppression List API Functionality Coming Soon

At SparkPost we’re constantly using feedback from our community to enhance our application and APIs. Based on what we’ve heard, we want to let you know about some new functionality that will be coming to our suppression list API in early November 2016.

  • We’ve heard you loud and clear and will be removing rate limiting on all Suppression List API calls. We’re improving the underlying data storage for this API, which allows us to remove the rate limiting that was put in place to guard against poor performance.
  • You will now be able to retrieve your entire suppression list. Each GET call to the API will include pagination so you can page through the results.
  • You will be able to search for suppression list entries by domain or description. For example, searching for all suppressions from gmail.
  • The PUT method on a single recipient is returning. You will no longer have to do a PUT to /api/v1/suppression-list and provide an array. Instead you can now do a PUT to /api/v1/suppression-list/[email protected] to update the [email protected] resource directly.

There will be no change in functionality for the existing create, update, and delete endpoints. While we always make our best effort to prevent breaking changes, we had to make an exception and will introduce a breaking change for GET calls to the Suppression List API.

Currently, GET calls return a response where each recipient contains two fields – transactional and non_transactional:

With the updates to the API, GET calls will now return a response where a recipient will show up for each type of suppression. For example, if a recipient is suppressed for both transactional and non-transactional emails, they will show up in the list twice with transactional or non-transactional set to true.  We also added type to reflect the boolean – set to either transactional or non_transactional:

Why we are making this change

Our initial implementation has several limitations:

  • Requests to the Suppression List API are rate limited.
  • Downloading the entire suppression list is not possible as the number of records returned is capped at 100,000.
  • It is not possible to distinguish why a recipient was added to the suppression list (e.g. hard bounce or spam complaint) for recipients that were suppressed for both transactional and non-transactional emails because there is only a single entry for each recipient. This data is contained in the source field. The same can be said about the updated and description fields.
  • It is not possible to make a PUT call to update a single entry in the suppression list.
  • The Web UI is limited. It does not load an initial page of suppressions and you cannot download your list.

Currently it takes several hours for a recipient to be suppressed and we agree this isn’t a great experience. In order to support a more real-time suppression, we swapped out the backing database and changed the data model to tune it for real-time lookups. With separate entries for each recipient for each type of suppression, it allows us to support more granular suppressions by more than just transactional/non-transactional flags.

Who’s affected

This change will only impact users that have suppressed a recipient for both transactional and non-transactional messages. More specifically, have code that make GET calls to the Suppression List API and are not iterating over the entire array to check the transactional/non-transactional booleans. Although we cannot read everyone’s code that has integrated against this API, we feel pretty confident that the number of users affected are very low, if any at all.

Necessary actions

If you have code that parses the response of the GET endpoints /api/v1/suppression-list or /api/v1/suppression-list/[email protected], you may have to add some additional code to iterate over your array to ensure you are parsing both the transactional and non-transactional records. If you are using subaccounts, you may already be iterating over the result but you may have to add additional logic to check for the transactional/non-transactional booleans. You can view the updated Suppression List API documentation with the improved response format here.

Making a tough decision

At SparkPost, we take backwards-compatibility very seriously. We don’t make these types of changes lightly and appreciate that our community has code in production using our API. We wanted to version the API but in this case it wouldn’t be feasible because the entire underlying architecture was changing. As a result, Taking all of the above feedback and issues into account, we believe the updates will provide a much better experience for our community in the long run.

Finally, if you’d like to discuss this update, or anything SparkPost related, please feel free to join us on our community Slack channel or reach out to us via Twitter.

—Bob Evans
Director of Application Engineering, SparkPost

SuppressionListAPIToday’s production release of SparkPost provides Suppression and unsubscribe functionality via a shiny new Email Suppression List API.

Why Do I Need This and How Does it Work?

Protecting your sender reputation is essential to maximizing your email deliverability. Many inbox providers, e.g. Yahoo, Gmail, Hotmail/, or AOL, opt to limit or refuse message traffic based on it. Continuing to send messages to invalid email addresses or to recipients who no longer want to receive your emails can negatively impact your sender reputation. By maintaining an up-to-date suppression list, you can avoid sending unwanted messages. A suppression list — or exclusion list, as it is sometimes called — is a list of recipient email addresses to which you do NOT want to send email.

SparkPost supports two types of email suppression lists: one (available via the Suppression List API) is specifically for your account, and a global suppression list. Message Systems maintains a global suppression list across all customers. NOTE: The Global Suppression List data is not accessible via the Email Suppression List API.

When a message is injected either using SMTP or HTTP, SparkPost will check the email address against the account-specific and global suppression lists. If an email address for a recipient matches an address on the list, that message will be rejected for delivery by SparkPost automatically.

How are Recipients added to Suppression Lists?

  • Spam Complaints / FeedBack Loops (FBLs): When a recipient clicks the “this is spam” button provided by the ISP, the ISP sends a Spam Complaint or FBL message to SparkPost. SparkPost will automatically add the recipient’s email address to your suppression list.
  • Hard Bounces: When messages bounce, the ISP will include a message that lets the sender know whether it was a “Soft Bounce” or a “Hard Bounce”. A “Soft Bounce” is a temporary error or delay indicating that the message was set to a valid recipient address, while a “Hard Bounce” indicates that the message was sent to an invalid email address that should not be retried. SparkPost will automatically add any email address associated with a “Hard Bounce” to your email suppression list.
  • Unsubscribe Requests: Recipients can request to be unsubscribed by clicking the SparkPost-provided unsubscribe link in the message or by using the List-Unsubscribe header. SparkPost will automatically add the recipient’s email address to the email suppression list.
  • Compliance Team: Recipients can contact Message Systems and request that they no longer receive messages from a particular sender. Protecting our customers’ brands and maintaining high deliverability across all Message Systems’ accounts is of the utmost importance. Message Systems’ Compliance Team ensures that we’re acting as a good sender within the email community across all our customers and takes requests of recipients very seriously. If a request is received, the Compliance Team will add the recipient’s email address to that sender’s suppression list.
  • Suppression List API: Using the REST API, you can insert/update a single entry or multiple entries in your suppression list, check the suppression status for a specific recipient, or remove a recipient from your suppression list. For more information, see the SparkPost Suppression List API.

How to Implement Link Unsubscribe Feature

The link unsubscribe features is easy to implement, simply add a link in your email in the following format:


That’s it. When users click on this link to unsubscribe, your webhook consumer will receive a link_unsubscribe event and that recipient will be added to your Suppression List.

How to Implement List-Unsubscribe Feature

The list unsubscribe features is baked into every message delivered by SparkPost by default. If you would like to know how to use this feature in your applications, read our user guide: Using Unsubscribe Events

Transactional vs. Non-Transactional Messages

SparkPost gives you the option to treat Transactional messages (such as password resets and shipping notifications) and non-Transactional messages (such as Marketing offers and newsletters) differently for the purpose of suppressing recipients. For example, you likely do not want to suppress recipients from your password reset messages, but do want to honor their request to stop receiving Marketing offers. By default, SparkPost treats your messages as non-Transactional. Designate any Template or Transmission as “Transactional” to bi-pass the Suppression List. Keep in mind — if you designate all your email as Transactional and recipients either opt-out or click “this is spam” but messages continue to go those recipients — your deliverability may suffer as a result. So think about what messages truly deserve to go no matter what vs. your recipients’ desire to opt-out of and designate accordingly.

For an example implementation, check out our user guide: Using Unsubscribe Events