Suppressions
One suppression list shared by every provider.
List suppressed addresses (shared across every provider)
GET /v1/suppressions
One list for every provider: an address that bounced or complained anywhere (provider webhooks, status polls, imported provider lists, send-time rejections) is never sent to again through any provider. Each entry says where it came from and, for temporary entries, when it ends.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
q | query | string | |
reason | query | string | |
limit | query | integer | Default 100. 1 to 500. |
cursor | query | string | |
origin | query | "webhook" | "webhook_unmatched" | "poll" | "sync" | "send" | "manual" | "import" | "escalation" | "unsubscribe" | "api" | … | Where entries came from (legacy: added before origins were recorded). |
connectionId | query | string | Entries that came from this sending provider connection. |
provider | query | string | |
scope | query | "all" | "broadcast" | |
temporary | query | "true" | "false" | true: only entries that end (repeated soft bounces, provider blocks); false: only permanent ones. |
expired | query | "true" | "false" | Include temporary entries that already ended (removed by housekeeping within the hour). Default false. |
Responses
{
"data": [{
"email": string,
"reason": "hard_bounce" | "complaint" | "unsubscribe" | "manual" | "blocked" | "soft_bounce_repeated",
"scope": "all" | "broadcast",
"source": string or null,
"createdAt": string,
"origin": "webhook" | "webhook_unmatched" | "poll" | "sync" | "send" | "manual" | "import" | "escalation" | "unsubscribe" | "api" | …,
"provider": string or null,
"connectionId": string or null,
"detail": string or null,
"expiresAt": string or null,
"updatedAt": string or null,
"allProviders": true
}],
"nextCursor": string or null
}Errors: 400, 401, 403, 404, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Suppress an address
POST /v1/suppressions
An existing hard bounce or complaint is never downgraded; the wider scope wins; a permanent entry replaces a temporary one.
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
emailrequired | string (email) | |
reason | "hard_bounce" | "complaint" | "unsubscribe" | "manual" | Default "manual". |
scope | "all" | "broadcast" | Default "all". |
Responses
{
"email": string,
"reason": "hard_bounce" | "complaint" | "unsubscribe" | "manual" | "blocked" | "soft_bounce_repeated",
"scope": "all" | "broadcast",
"source": string or null,
"createdAt": string,
"origin": "webhook" | "webhook_unmatched" | "poll" | "sync" | "send" | "manual" | "import" | "escalation" | "unsubscribe" | "api" | …,
"provider": string or null,
"connectionId": string or null,
"detail": string or null,
"expiresAt": string or null,
"updatedAt": string or null,
"allProviders": true
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Suppression counts by reason, origin and provider connection
GET /v1/suppressions/stats
Entries in force (temporary entries that ended are not counted).
Authentication: Authorization: Bearer with an API key or a session token.
Responses
{
"total": number,
"byReason": map of number,
"byOrigin": map of number,
"byConnection": map of number
}Errors: 400, 401, 403, 404, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Provider suppression sync status per connection
GET /v1/suppressions/sync
For each connected provider: whether its own suppression list can be imported, the last run and its result, and the next run. Lists are imported when a provider is connected and then every few hours (providerSync.intervalHours, default 6).
Authentication: Authorization: Bearer with an API key or a session token.
Responses
{
"data": [{
"connectionId": string,
"provider": string,
"name": string,
"kind": "suppressions" | "suppressions_push" | "status",
"supported": boolean,
"status": "idle" | "running" | "error" | "unsupported",
"inProgress": boolean,
"lastRunAt": string or null,
"lastSuccessAt": string or null,
"nextRunAt": string or null,
"lastResult": {
"ok": boolean,
"at": string,
"imported": number,
"updated": number,
"seen": number,
"pushed": number,
"polled": number,
"events": number,
"pages": number,
"done": boolean,
"error": string or null,
"unsupported": boolean
},
"total": number
}]
}Errors: 400, 401, 403, 404, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Import provider suppression lists now
POST /v1/suppressions/sync
Starts an import of the providers' own suppression lists in the background (GET /v1/suppressions/sync shows progress).
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
connectionId | string | One connection; default: every connection that supports it. |
Responses
{
"data": [{
"connectionId": string,
"provider": string,
"name": string,
"kind": "suppressions" | "suppressions_push" | "status",
"supported": boolean,
"status": "idle" | "running" | "error" | "unsupported",
"inProgress": boolean,
"lastRunAt": string or null,
"lastSuccessAt": string or null,
"nextRunAt": string or null,
"lastResult": {
"ok": boolean,
"at": string,
"imported": number,
"updated": number,
"seen": number,
"pushed": number,
"polled": number,
"events": number,
"pages": number,
"done": boolean,
"error": string or null,
"unsupported": boolean
},
"total": number
}]
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Remove an address from the suppression list
DELETE /v1/suppressions/{email}
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
emailrequired | path | string |
Responses
Errors: 400, 401, 403, 404, 409, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)