Managing List Items via the API in SuppressionList

You can add items to and remove items from your list via API:

Adding List Items

$ curl -X POST https://app.suppressionlist.com/lists/my_list/items \
       -H 'Accept: application/json' \
       -H 'Content-Type: application/json' \
       -d '{"values":"test@email.com"}' \
       -uAPI:fc36c8168cbb16784f6a29f89695dd92

Response

HTTP/1.1 200 OK
 Content-Type: application/json; charset=utf-8
 {
   "accepted": 1,
   "rejected": 0
 }

You can add multiple items in a single call:

$ curl -X POST https://app.suppressionlist.com/lists/my_list/items \
       -H 'Accept: application/json' \
       -H 'Content-Type: application/json' \
       -d '{"values":"test@email.com|test2@email.com|test3@email.com"}' \
       -uAPI:fc36c8168cbb16784f6a29f89695dd92

Setting an item’s timestamp

Optionally you may use the `timestamp` property to set the timestamp of the item on the list. A wide variety of formats are accepted, but ISO8601 is recommended. If the `timestamp` provided cannot be understood, then an HTTP 422 will be returned and the value(s) will not be added. If a timestamp is not provided, the current system time will be used.

$ curl -X POST https://app.suppressionlist.com/lists/my_list/items \
        -H 'Accept: application/json' \
        -H 'Content-Type: application/json' \
        -d '{"values":["test@email.com"],"timestamp":"2015-08-26T17:29:32Z"}'
        -uAPI:fc36c8168cbb16784f6a29f89695dd92
 
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
   "accepted": 1,
   "rejected": 0
}

A Note About MD5 Hashing

For data security all Lists store their data in MD5-hashed form. The system will do its best to do the right thing when adding values to a List. If you submit a non-hashed value, SuppressionList will automatically hash it before adding it to the List. If you submit a string that looks like an md5 hash (32 characters long using only 0-9 and a-f), SuppressionList will add that value directly to the List without re-hashing it.

Standardizing data

Upon receiving a item to add to a List or a term to query, SuppressionList will take the following steps:

1. Strip leading and trailing whitespace from the query string
2. Downcase all characters in the query string
3. MD5 hash the query string before performing the add or query.

Note that punctuation is not removed, only whitespace. So phone number formats, for example, are not standardized. We recommend that you standardize all data before adding it to a list as well as before querying.

Remove Items From a List

Use an HTTP DELETE request to https://app.suppressionlist.com/lists/list_id/items with the items you’d like to remove contained in a param named ‘values’.

$ curl -X DELETE https://app.suppressionlist.com/lists/my_list/items \
       -H 'Accept: application/json' \
       -H 'Content-Type: application/json' \
       -d '{"values":"test@email.com"}' \
       -uAPI:fc36c8168cbb16784f6a29f89695dd92

Response

HTTP/1.1 200 OK
 Content-Type: application/json; charset=utf-8
 {
   "deleted": 1
 }

You can remove multiple items in a single call:

$ curl -X DELETE https://app.suppressionlist.com/lists/my_list/items \
       -H 'Accept: application/json' \
       -H 'Content-Type: application/json' \
       -d '{"values":"test@email.com|test2@email.com|test3@email.com"}' \
       -uAPI:fc36c8168cbb16784f6a29f89695dd92