Suppression API

The Suppression API adds records to a suppression list, deletes them, and downloads a whole list as a file. A request carries up to 10,000 items, and the Suppression API permission on your API key decides which of the three you can do.

Instructions

1. Give your API Key the right Suppression API permission: Full Access to add or delete, Read Only to download. Account > API Keys > select key > set the permission > Save > Copy.
2. Go to API Documentation > Suppression API. It has four tabs: POST Download, GET Download, POST Records and DELETE Records. Each lists its response codes with example bodies.
3. Add records: POST /api/SuppressionList/{listId}/Records with {"items": [...]}. Up to 10,000 items per request. Success is a 201, not a 200.
4. Delete records: DELETE /api/SuppressionList/{listId}/Records?items=a&items=b. The items parameter is repeated once per entry and URL-encoded. Up to 10,000 items, and keep the whole URL under 2,000 characters. The URL length runs out first in practice, because every item is spelled out in it, so split a long delete across several requests.
5. Download: POST /api/SuppressionList/{listId}/Downloads returns a 201 with a downloadLink. Then GET that link for a ZIP holding a CSV.
6. The file is built in the background, so a 404 right after the request is normal. Poll until it returns a 200. The 404 body says which state it is in: still in progress, expired, failed, or not found.
7. A download expires one day after it is created. After that, request a new one.
8. Records must match the suppression list format — Email, MD5, SHA512, Domain or Pattern. Items that do not match are rejected.
9. Adding and deleting use the same 10% batch rule as the Contact API. More than 10% of items failing rejects the whole request with a 400 and changes nothing. 10% or fewer failing succeeds, applies the rest, and reports the failures in messages.
10. Each entry in messages is { "suppresssionData": ..., "errorMessage": ... }. The key is suppresssionData, with three s's. Code looking for suppressionData finds nothing.
11. An unknown suppression list id is a 400, not a 404. There is no rate limit response on this API.

Related pages

• Suppression API Reference — covers Calls, Authentication, Limits, Add Records
• Suppression API Walkthrough — every step with screenshots, covering Prerequisites, Step 1: Configure API Key Permissions, Step 2: Find Your Suppression List ID