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/test@example.com to update the test@example.com 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/foo@bar.com, 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