---
title: "Deliverability API"
description: "Deliverability in the OneSend API: 13 endpoints. Method, path, parameters, request body and response shape for each."
url: https://onesend.email/docs/api-reference/deliverability/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/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](https://onesend.email/docs/api-reference/#authentication) and errors are described in the [overview](https://onesend.email/docs/api-reference/).

## 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.

| Field | Type | Description |
|---|---|---|
| `campaign` | `object` |  |
| `campaign.enabled` | `boolean` |  |
| `campaign.bounceRate` | `number` | Pause a sending campaign when hard bounces / sent exceed this (0.025 = 2.5%). 0.005 to 0.1. |
| `campaign.complaintRate` | `number` | Pause when spam complaints / delivered exceed this (0.0008 = 0.08%). 0.0002 to 0.005. |
| `campaign.minSample` | `integer` | Emails sent before the rates are judged (50 to 10,000). |
| `campaign.minSampleFraction` | `number` | Or this share of the recipients when smaller (0.01 to 0.5; never fewer than 20 emails). |
| `workspace` | `object` |  |
| `workspace.enabled` | `boolean` |  |
| `workspace.bounceRate` | `number` | Block new campaign sends when the hard bounce rate over the window exceeds this (0.01 to 0.2). |
| `workspace.complaintRate` | `number` | Block new campaign sends when the complaint rate over the window exceeds this (0.0005 to 0.02). |
| `workspace.windowDays` | `integer` |  |
| `workspace.minSample` | `integer` |  |
| `warmup` | `object` |  |
| `warmup.enabled` | `boolean` |  |
| `warmup.startPerDay` | `integer` |  |
| `warmup.targetPerDay` | `integer` |  |
| `warmup.days` | `integer` |  |
| `pacing` | `object` |  |
| `pacing.enabled` | `boolean` |  |
| `pacing.firstDayPerProvider` | `integer` |  |
| `pacing.growth` | `number` |  |
| `engagementOrdering` | `boolean` |  |
| `quality` | `object` |  |
| `quality.exclude` | `array of "ok" \| "invalid" \| "typo" \| "no_mx" \| "disposable" \| "role"` |  |
| `sunset` | `object` |  |
| `sunset.enabled` | `boolean` |  |
| `sunset.rule` | `"campaigns" \| "days"` |  |
| `sunset.campaigns` | `integer` |  |
| `sunset.days` | `integer` |  |
| `sunset.graceDays` | `integer` |  |
| `sunset.templateId` | `string or null` |  |
| `sunset.fromEmail` | `string or null` |  |
| `sunset.fromName` | `string or null` |  |
| `sunset.subject` | `string or null` |  |
| `includeSandbox` | `boolean` |  |
| `routing` | `object` |  |
| `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.campaignAffinity` | `boolean` | A campaign keeps sending through one provider while that provider can send. |
| `routing.spilloverShare` | `number` | When 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.spilloverMinPerHour` | `integer` | Emails per hour that may always move, however small the campaign (1 to 100,000). |
| `providerHealth` | `object` |  |
| `providerHealth.enabled` | `boolean` |  |
| `providerHealth.bounceRate` | `number` | Take a provider out of rotation for campaigns when its hard bounce rate over 24 hours or 7 days exceeds this (0.04 = 4%). |
| `providerHealth.complaintRate` | `number` | Or its spam complaint rate exceeds this (0.001 = 0.1%). |
| `providerHealth.minSample24h` | `integer` | Emails sent in 24 hours before the 24-hour rates are judged. |
| `providerHealth.minSample7d` | `integer` | Emails sent in 7 days before the 7-day rates are judged. |
| `providerHealth.severeFactor` | `number` | Severe = this many times a threshold: the provider is also taken out of rotation for transactional email. |
| `providerHealth.transactional` | `boolean` | Apply the severe rule to transactional email (a provider out of rotation is still used when no other provider can send). |
| `providerHealth.cooldownHours` | `integer` | Hours before a provider out of rotation is judged again, on email sent after it was taken out. |
| `softBounces` | `object` |  |
| `softBounces.enabled` | `boolean` |  |
| `softBounces.count` | `integer` | Soft bounces for one address within the window that suppress it for a while. |
| `softBounces.windowDays` | `integer` |  |
| `softBounces.suppressDays` | `integer` | Days the temporary suppression lasts. |
| `providerSync` | `object` |  |
| `providerSync.enabled` | `boolean` | Import each provider's suppression list when connected and then periodically. |
| `providerSync.intervalHours` | `integer` |  |
| `providerSync.push` | `boolean` | Also add suppressions to providers that support it (off by default: the provider list may be shared with other apps). |
| `statusPolling` | `object` |  |
| `statusPolling.mode` | `"auto" \| "always" \| "off"` | `auto`: ask the provider API for the delivery status of recent emails when no webhook arrived recently. |
| `statusPolling.quietHours` | `integer` | Hours without a webhook after which `auto` starts polling a connection. |
| `statusPolling.maxAgeHours` | `integer` | Emails 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

| Name | In | Type | Description |
|---|---|---|---|
| `domain`required | path | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `status`required | `"warming" \| "off" \| "established"` |  |
| `restart` | `boolean` |  |

### 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.

| Field | Type | Description |
|---|---|---|
| `emails`required | `array of string` | At most 1000 items. |
| `dns` | `boolean` |  |

### 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.

| Field | Type | Description |
|---|---|---|
| `ids` | `array of string` | At most 10000 items. |
| `all` | `boolean` |  |

### 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`)
