Docs / API reference

Suppressions

One suppression list shared by every provider.

Base URL https://your-server.example (your OneSend server). Authentication and errors are described in the overview.

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

NameInTypeDescription
qquerystring
reasonquerystring
limitqueryintegerDefault 100. 1 to 500.
cursorquerystring
originquery"webhook" | "webhook_unmatched" | "poll" | "sync" | "send" | "manual" | "import" | "escalation" | "unsubscribe" | "api" | …Where entries came from (legacy: added before origins were recorded).
connectionIdquerystringEntries that came from this sending provider connection.
providerquerystring
scopequery"all" | "broadcast"
temporaryquery"true" | "false"true: only entries that end (repeated soft bounces, provider blocks); false: only permanent ones.
expiredquery"true" | "false"Include temporary entries that already ended (removed by housekeeping within the hour). Default false.

Responses

200 Success

{
  "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
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

application/json, required.

FieldTypeDescription
emailrequiredstring (email)
reason"hard_bounce" | "complaint" | "unsubscribe" | "manual"Default "manual".
scope"all" | "broadcast"Default "all".

Responses

201 Success

{
  "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
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

200 Success

{
  "total": number,
  "byReason": map of number,
  "byOrigin": map of number,
  "byConnection": map of number
}
Errors: 400, 401, 403, 404, 429, 500
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

200 Success

{
  "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
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

application/json, required.

FieldTypeDescription
connectionIdstringOne connection; default: every connection that supports it.

Responses

202 Success

{
  "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
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

NameInTypeDescription
emailrequiredpathstring

Responses

204 No content

Errors: 400, 401, 403, 404, 409, 429, 500
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)