How Do I Download an Entire Suppression List

May 12, 2017 Contributors

SparkPost’s Suppression API takes advantage of paging cursors to retrieve large datasets. Using the cursor parameter allows users to download an entire suppression list if they wish or a full subset of their list if they wish to provide filter parameters like domain or type.

# How?

First things first, you’ll need to add the cursor query parameter to your request with the special value initial. This will retrieve the first page of results. When using the cursor query parameter each page retrieves 1,000 results by default. If you’d like, you can supply per_page as a query parameter with a value up to 10,000 to make fewer requests.

Every response from the suppression API has 3 top level properties: "results", "links", and "total_count". When cursor is passed as a query parameter, the "links" array has references to the first (initial) page and the next page with appropriate cursors defined. Using the URL in the “next” reference will allow the user to retrieve the second page and so forth.

# Seems Tedious

Doing this manually is obviously a lot of work if you have a large list. However its pretty simple to do if you have a script. I wrote an example nodejs script to handle the paging automatically.

It logs the suppressions to the console but they can easily be piped to a new line delimited json file. To use it :

  • Put the code above in get-all-suppressions.js replacing <keys> with your API key
  • npm i lodash request
  • node get-all-suppressions >> suppressions.ndjson