Docs / API reference

Deliverability

Safeguards that protect your provider accounts: automatic campaign pause on high bounce or complaint rates, a workspace guard, warm-up of new sending domains, pacing per mailbox provider, address quality checks, sunsetting of inactive contacts and best time to send.

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

Deliverability overview

GET /v1/deliverability

Bounce, complaint and open rates for the last 7 and 30 days with the thresholds, the workspace guard, warm-up per sending domain, paused campaigns with reasons, contact quality and inactive counts, and the best time to send.

Authentication: Authorization: Bearer with an API key or a session token.

Responses

200 Success

{
  "rates": {
    "last7Days": {
      "sent": number,
      "delivered": number,
      "hardBounces": number,
      "complaints": number,
      "uniqueOpens": number,
      "bounceRate": number,
      "complaintRate": number,
      "openRate": number
    },
    "last30Days": {
      "sent": number,
      "delivered": number,
      "hardBounces": number,
      "complaints": number,
      "uniqueOpens": number,
      "bounceRate": number,
      "complaintRate": number,
      "openRate": number
    }
  },
  "settings": {
    "campaign": {
      "enabled": boolean,
      "bounceRate": number,
      "complaintRate": number,
      "minSample": integer,
      "minSampleFraction": number
    },
    "workspace": {
      "enabled": boolean,
      "bounceRate": number,
      "complaintRate": number,
      "windowDays": integer,
      "minSample": integer
    },
    "warmup": {
      "enabled": boolean,
      "startPerDay": integer,
      "targetPerDay": integer,
      "days": integer
    },
    "pacing": {
      "enabled": boolean,
      "firstDayPerProvider": integer,
      "growth": number
    },
    "engagementOrdering": boolean,
    "quality": {
      "exclude": ["ok" | "invalid" | "typo" | "no_mx" | "disposable" | "role"]
    },
    "sunset": {
      "enabled": boolean,
      "rule": "campaigns" | "days",
      "campaigns": integer,
      "days": integer,
      "graceDays": integer,
      "templateId": 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)

Deliverability alerts for the dashboard

GET /v1/deliverability/alerts

Campaigns paused by a safeguard and whether new campaign sends are blocked.

Authentication: Authorization: Bearer with an API key or a session token.

Responses

200 Success

{
  "data": [{
    "level": "warning" | "error",
    "code": string,
    "title": string,
    "message": string,
    "href": string
  }]
}
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)

Deliverability settings

GET /v1/deliverability/settings

Authentication: Authorization: Bearer with an API key or a session token.

Responses

200 Success

{
  "campaign": {
    "enabled": boolean,
    "bounceRate": number,
    "complaintRate": number,
    "minSample": integer,
    "minSampleFraction": number
  },
  "workspace": {
    "enabled": boolean,
    "bounceRate": number,
    "complaintRate": number,
    "windowDays": integer,
    "minSample": integer
  },
  "warmup": {
    "enabled": boolean,
    "startPerDay": integer,
    "targetPerDay": integer,
    "days": integer
  },
  "pacing": {
    "enabled": boolean,
    "firstDayPerProvider": integer,
    "growth": number
  },
  "engagementOrdering": boolean,
  "quality": {
    "exclude": ["ok" | "invalid" | "typo" | "no_mx" | "disposable" | "role"]
  },
  "sunset": {
    "enabled": boolean,
    "rule": "campaigns" | "days",
    "campaigns": integer,
    "days": integer,
    "graceDays": integer,
    "templateId": string or null,
    "fromEmail": string or null,
    "fromName": string or null,
    "subject": string or null
  },
  "includeSandbox": boolean,
  "routing": {
    "recipientAffinity": "auto" | "recipient" | "off",
    "campaignAffinity": boolean,
    "spilloverShare": number,
    "spilloverMinPerHour": integer
  },
  "providerHealth": {
    "enabled": boolean,
    "bounceRate": number,
    "complaintRate": number,
    "minSample24h": integer,
    "minSample7d": integer,
    "severeFactor": number,
    "transactional": boolean,
    "cooldownHours": integer
  },
  "softBounces": {
    "enabled": boolean,
  …
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)

Change deliverability settings

PATCH /v1/deliverability/settings

Only the fields you send change. Numbers outside their bounds are refused with 400 invalid_settings (see the settings schema for each range). Turning on sunsetting needs a re-engagement template and a sender address.

Authentication: Authorization: Bearer with an API key or a session token.

Request body

application/json, required.

FieldTypeDescription
campaignobject
campaign.enabledboolean
campaign.bounceRatenumberPause a sending campaign when hard bounces / sent exceed this (0.025 = 2.5%). 0.005 to 0.1.
campaign.complaintRatenumberPause when spam complaints / delivered exceed this (0.0008 = 0.08%). 0.0002 to 0.005.
campaign.minSampleintegerEmails sent before the rates are judged (50 to 10,000).
campaign.minSampleFractionnumberOr this share of the recipients when smaller (0.01 to 0.5; never fewer than 20 emails).
workspaceobject
workspace.enabledboolean
workspace.bounceRatenumberBlock new campaign sends when the hard bounce rate over the window exceeds this (0.01 to 0.2).
workspace.complaintRatenumberBlock new campaign sends when the complaint rate over the window exceeds this (0.0005 to 0.02).
workspace.windowDaysinteger
workspace.minSampleinteger
warmupobject
warmup.enabledboolean
warmup.startPerDayinteger
warmup.targetPerDayinteger
warmup.daysinteger
pacingobject
pacing.enabledboolean
pacing.firstDayPerProviderinteger
pacing.growthnumber
engagementOrderingboolean
qualityobject
quality.excludearray of "ok" | "invalid" | "typo" | "no_mx" | "disposable" | "role"
sunsetobject
sunset.enabledboolean
sunset.rule"campaigns" | "days"
sunset.campaignsinteger
sunset.daysinteger
sunset.graceDaysinteger
sunset.templateIdstring or null
sunset.fromEmailstring or null
sunset.fromNamestring or null
sunset.subjectstring or null
includeSandboxboolean
routingobject
routing.recipientAffinity"auto" | "recipient" | "off"Prefer the provider that last accepted email for the recipient. auto: per mailbox provider for Gmail, Microsoft and Yahoo addresses, per address otherwise.
routing.campaignAffinitybooleanA campaign keeps sending through one provider while that provider can send.
routing.spilloverSharenumberWhen the campaign's provider cannot send, the share of the campaign that may move to other providers per hour (0.01 to 1; 1 = no cap). The rest waits.
routing.spilloverMinPerHourintegerEmails per hour that may always move, however small the campaign (1 to 100,000).
providerHealthobject
providerHealth.enabledboolean
providerHealth.bounceRatenumberTake a provider out of rotation for campaigns when its hard bounce rate over 24 hours or 7 days exceeds this (0.04 = 4%).
providerHealth.complaintRatenumberOr its spam complaint rate exceeds this (0.001 = 0.1%).
providerHealth.minSample24hintegerEmails sent in 24 hours before the 24-hour rates are judged.
providerHealth.minSample7dintegerEmails sent in 7 days before the 7-day rates are judged.
providerHealth.severeFactornumberSevere = this many times a threshold: the provider is also taken out of rotation for transactional email.
providerHealth.transactionalbooleanApply the severe rule to transactional email (a provider out of rotation is still used when no other provider can send).
providerHealth.cooldownHoursintegerHours before a provider out of rotation is judged again, on email sent after it was taken out.
softBouncesobject
softBounces.enabledboolean
softBounces.countintegerSoft bounces for one address within the window that suppress it for a while.
softBounces.windowDaysinteger
softBounces.suppressDaysintegerDays the temporary suppression lasts.
providerSyncobject
providerSync.enabledbooleanImport each provider's suppression list when connected and then periodically.
providerSync.intervalHoursinteger
providerSync.pushbooleanAlso add suppressions to providers that support it (off by default: the provider list may be shared with other apps).
statusPollingobject
statusPolling.mode"auto" | "always" | "off"auto: ask the provider API for the delivery status of recent emails when no webhook arrived recently.
statusPolling.quietHoursintegerHours without a webhook after which auto starts polling a connection.
statusPolling.maxAgeHoursintegerEmails older than this are not polled.

Responses

200 Success

{
  "campaign": {
    "enabled": boolean,
    "bounceRate": number,
    "complaintRate": number,
    "minSample": integer,
    "minSampleFraction": number
  },
  "workspace": {
    "enabled": boolean,
    "bounceRate": number,
    "complaintRate": number,
    "windowDays": integer,
    "minSample": integer
  },
  "warmup": {
    "enabled": boolean,
    "startPerDay": integer,
    "targetPerDay": integer,
    "days": integer
  },
  "pacing": {
    "enabled": boolean,
    "firstDayPerProvider": integer,
    "growth": number
  },
  "engagementOrdering": boolean,
  "quality": {
    "exclude": ["ok" | "invalid" | "typo" | "no_mx" | "disposable" | "role"]
  },
  "sunset": {
    "enabled": boolean,
    "rule": "campaigns" | "days",
    "campaigns": integer,
    "days": integer,
    "graceDays": integer,
    "templateId": string or null,
    "fromEmail": string or null,
    "fromName": string or null,
    "subject": string or null
  },
  "includeSandbox": boolean,
  "routing": {
    "recipientAffinity": "auto" | "recipient" | "off",
    "campaignAffinity": boolean,
    "spilloverShare": number,
    "spilloverMinPerHour": integer
  },
  "providerHealth": {
    "enabled": boolean,
    "bounceRate": number,
    "complaintRate": number,
    "minSample24h": integer,
    "minSample7d": integer,
    "severeFactor": number,
    "transactional": boolean,
    "cooldownHours": integer
  },
  "softBounces": {
    "enabled": boolean,
  …
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)

Workspace guard

GET /v1/deliverability/guard

Whether new campaign sends are blocked because the bounce or complaint rate of the last 7 days is too high. Transactional email is never blocked.

Authentication: Authorization: Bearer with an API key or a session token.

Responses

200 Success

{
  "blocked": boolean,
  "code": string or null,
  "message": string or null,
  "blockedAt": string or null,
  "acknowledgedAt": string or null,
  "bounceRate": number,
  "complaintRate": number,
  "sample": 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)

Acknowledge the workspace guard

POST /v1/deliverability/acknowledge

The workspace owner or an admin confirms they reviewed the bounce or complaint problem. New campaigns can be sent again; the guard then judges only email sent after this moment. Needs a signed-in owner or admin.

Authentication: Authorization: Bearer with an API key or a session token.

Responses

200 Success

{
  "blocked": boolean,
  "code": string or null,
  "message": string or null,
  "blockedAt": string or null,
  "acknowledgedAt": string or null,
  "bounceRate": number,
  "complaintRate": number,
  "sample": number
}
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)

Warm-up per sending domain

GET /v1/deliverability/warmup

Authentication: Authorization: Bearer with an API key or a session token.

Responses

200 Success

{
  "data": [{
    "domain": string,
    "status": "new" | "warming" | "complete" | "off" | "established",
    "day": number or null,
    "days": number,
    "todayLimit": number or null,
    "plannedToday": number,
    "startedAt": 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)

Change the warm-up of a sending domain

PATCH /v1/deliverability/warmup/{domain}

warming starts (or with restart: true restarts) the ramp today, off turns warm-up off for the domain, established marks it as already having a sending reputation.

Authentication: Authorization: Bearer with an API key or a session token.

Parameters

NameInTypeDescription
domainrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
statusrequired"warming" | "off" | "established"
restartboolean

Responses

200 Success

{
  "data": [{
    "domain": string,
    "status": "new" | "warming" | "complete" | "off" | "established",
    "day": number or null,
    "days": number,
    "todayLimit": number or null,
    "plannedToday": number,
    "startedAt": string or null
  }]
}
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)

Best time to send

GET /v1/deliverability/best-time

Opens per UTC hour over the last 30 days and the hour with the most opens, in UTC and in the workspace time zone.

Authentication: Authorization: Bearer with an API key or a session token.

Responses

200 Success

{
  "hour": number or null,
  "localHour": number or null,
  "timezone": string,
  "histogram": [number],
  "opens": number,
  "suggestion": 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)

Check address quality

POST /v1/deliverability/quality/check

Syntax, mistyped domains (with a suggestion), domains without a mail server (MX or A record, cached), temporary-address domains and role addresses, for up to 1,000 addresses. Nothing is stored. dns: false skips the mail server lookup.

Authentication: Authorization: Bearer with an API key or a session token.

Request body

application/json, required.

FieldTypeDescription
emailsrequiredarray of stringAt most 1000 items.
dnsboolean

Responses

200 Success

{
  "data": [{
    "input": string,
    "email": string or null,
    "domain": string or null,
    "quality": "ok" | "invalid" | "typo" | "no_mx" | "disposable" | "role",
    "flags": ["ok" | "invalid" | "typo" | "no_mx" | "disposable" | "role"],
    "suggestion": string or null,
    "mx": "found" | "implicit" | "missing" | "unknown" | "skipped",
    "reason": string or null,
    "excludedByDefault": boolean
  }]
}
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)

Re-check the address quality of every contact

POST /v1/deliverability/quality/recheck

Clears the stored results; the background check runs again (mail server lookups are cached for 7 days). Up to 500 contacts are checked right away.

Authentication: Authorization: Bearer with an API key or a session token.

Responses

202 Success

{
  "queued": number,
  "checked": number
}
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)

Restore inactive contacts

POST /v1/deliverability/inactive/restore

Sets inactive contacts back to subscribed and resets their sunsetting state. Send ids, or all: true.

Authentication: Authorization: Bearer with an API key or a session token.

Request body

application/json, required.

FieldTypeDescription
idsarray of stringAt most 10000 items.
allboolean

Responses

200 Success

{
  "restored": 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)

Run sunsetting now

POST /v1/deliverability/sunset/run

Sends due re-engagement emails and marks contacts inactive whose grace period ended. Runs automatically every few minutes while sunsetting is on.

Authentication: Authorization: Bearer with an API key or a session token.

Responses

200 Success

{
  "reengaged": number,
  "deactivated": number,
  "skipped": string or null
}
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)