Reference
List suppression lists
GET /v1/suppressions. The organisation's suppression lists.
GET /v1/suppressions
The organisation's suppression lists. With since, only lists changed after that time, each with the records added since, so objections that reach records you hold can be pulled as well as received by webhook.
| Property | Value |
|---|---|
| Endpoint | GET https://mydatahub.emailmovers.com/v1/suppressions |
| Operation id | listSuppressions |
| Cost | Free (0 credits) |
| Access | An API key or an OAuth 2.1 token with the scope suppressions:read. |
| Tag | Suppressions |
Request
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
since | query | string (date-time) | no | Only lists changed after this time. |
limit | query | integer (1 to 100) | no | Items per page, 1 to 100. Default 25. |
cursor | query | string | no | An opaque cursor from next_cursor. Pass it back unchanged. |
MyDataHub-Version | header | string | no | The dated API version, pinned per key when left out. Non-breaking changes ship as new dates; the path major changes only for breaking changes, with a 12 month deprecation window. |
Example request
curl "https://mydatahub.emailmovers.com/v1/suppressions" \
-H "Authorization: Bearer $MYDATAHUB_API_KEY"Responses
200: A page of suppression lists.
Headers: RateLimit, RateLimit-Policy.
| Member | Type | Always present | Description |
|---|---|---|---|
data | array of SuppressionList | yes | |
data[].id | string | yes | Format: a suppression list id: sup_ followed by a 26 character ULID in upper case Crockford base32, such as sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA. |
data[].name | string | yes | |
data[].kind | enum: email, domain, phone, company_number, title_term | yes | |
data[].source | enum: upload, objections | yes | upload for a list you sent; objections for the organisation's own list, which gathers objections you report and database-wide objections on records you hold. |
data[].row_count | integer (0 or more) | yes | |
data[].created_at | string (date-time) | yes | |
data[].updated_at | string (date-time) | yes | |
data[].created_by | string or null | yes | |
data[].added_since | array of SuppressionNotice | no | With since: the records added to this list after that time, for pull. |
has_more | boolean | yes | |
next_cursor | string or null | yes |
Example response
{
"data": [
{
"id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA",
"name": "Existing customers",
"kind": "email",
"source": "upload",
"row_count": 1198,
"created_at": "2026-09-20T14:02:00Z",
"updated_at": "2026-09-20T14:02:00Z",
"created_by": "usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8"
}
],
"has_more": false,
"next_cursor": null
}Errors
Every error is a problem object with a code and a next_step. Every response carries the RateLimit and RateLimit-Policy headers; see Rate limits.
| Status | Problem codes | When |
|---|---|---|
| 400 | invalid-request, idempotency-key-required, unsupported-version | The request could not be read, or an Idempotency-Key is missing. |
| 401 | authentication-required, account-required | Sign in (OAuth) or send an API key (authentication-required), or create a free account for what the anonymous tier does not cover (account-required). |
| 403 | insufficient-scope, confirmation-required, business-details-required, licence-acceptance-required, dpa-acceptance-required, agent-budget-exceeded | The token lacks a scope (insufficient-scope, with required_scope and a WWW-Authenticate step-up challenge); no person confirmed the spend and no agent key covers it (confirmation-required, with an approval_url); an agent key's per-order cap or monthly budget does not cover it (agent-budget-exceeded); an account made by self-serve sign-up has not yet confirmed its business name and that it is a UK business, which its first order needs (business-details-required); the order needs the Data Licence and Sharing Agreement accepted at the version in force (licence-acceptance-required); or a suppression upload comes before the organisation has accepted the Article 28 data processing agreement in force (dpa-acceptance-required). Nothing is charged. |
| 422 | validation-failed, quote-required, dataset-unavailable | The request is not valid. errors lists every problem with a JSON pointer and did_you_mean. |
| 429 | rate-limited | Too many requests. Wait for Retry-After. |
| Any other failure | internal-error, service-unavailable, tps-screen-expired | Something failed on our side (500 internal-error) or the service is briefly unavailable (503 service-unavailable, with Retry-After). Nothing was charged; retry with the same Idempotency-Key. A count, sample, quote or order with telephone in play is also refused with 503 tps-screen-expired, with no Retry-After, while the dataset version's TPS and CTPS screen is more than 28 days old. |