Lists

Upload a file and receive a reusable suppression list ID

Send an uncompressed UTF-8 text file as the request body, one domain or HTTP(S) URL per line with no header. No name, sizeBytes, reservation or completion request is required. A 202 Accepted response contains the reusable ID after the file has been stored. Validation runs asynchronously: fetch the ID every two seconds while Pending or Validating, and use it only when Ready. Invalid status includes an error explaining rejected content or account storage quota. Validation may finish before the upload response arrives. No credits are spent. All API keys share account limits of 20 uploads per UTC day, two simultaneous uploads, 20 MiB per file, 250,000 unique domains per list, and 100 MiB validated storage, including retained snapshots. Storage is checked after validation. Rejected files and temporary uploads are removed; interrupted uploads are scheduled for cleanup after 15 minutes, with cleanup retries every five minutes. The upload deadline is 60 seconds; validation happens afterwards. Processing has a one-hour deadline including retries; expired jobs are rejected and cleaned up. Every upload creates a new ID. After a lost response, inspect existing IDs before uploading again. Errors may include an id whose status can be fetched.

post/lists/suppressions

Request

Query parameters

namestring

Optional label. Defaults to the returned ID.

Request body text/plain

string binary required

Uncompressed UTF-8 file, from 1 to 20,971,520 bytes.

Response

File stored and queued for validation. Fetch the returned ID until Ready or Invalid.

idstring required
namestring required
status'Pending' | 'Validating' | 'Ready' | 'Invalid' | 'Retired' | 'Deleted' required
createdAtinteger required

UNIX timestamp in seconds.

domainCountinteger
sizeBytesinteger

Validated snapshot size in bytes.

errorstring
retiredAtinteger

Changes

No recorded changes to this operation across all 1 revision of this API.