---
title: "Campaigns API"
description: "Campaigns in the OneSend API: 17 endpoints. Marketing campaigns: draft, schedule, send through your providers, and report."
url: https://onesend.email/docs/api-reference/campaigns/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/docs/api-reference/)

# Campaigns

Marketing campaigns: draft, schedule, send through your providers, and report.

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/).

## List campaigns with headline stats

GET `/v1/campaigns`

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

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `cursor` | query | `string` |  |
| `limit` | query | `integer` | Default 50. 1 to 200. |
| `status` | query | `string` |  |
| `q` | query | `string` |  |

### Responses

`200` Success

```
{
  "data": [{
    "id": string,
    "object": "campaign",
    "name": string,
    "status": "draft" | "scheduled" | "sending" | "sent" | "paused" | "canceled" | "failed",
    "subject": string,
    "previewText": string or null,
    "fromName": string,
    "fromEmail": string,
    "replyTo": string or null,
    "templateId": string or null,
    "recipients": {
      "listIds": [string],
      "segmentIds": [string],
      "excludeListIds": [string]
    },
    "tracking": {
      "opens": boolean,
      "clicks": boolean,
      "utm": { … }
    },
    "currency": string,
    "tags": [string],
    "policyId": string or null,
    "scheduledAt": string or null,
    "sentAt": string or null,
    "estimatedRecipients": number or null,
    "plan": {
      "perDay": number,
      "days": number,
      "unlimited": boolean,
      "limitedBy": "quota" | "warmup" | "pacing",
      "reason": string,
      "domain": string
    },
    "delivery": {
      "bestTime": boolean,
      "includeQualityIssues": boolean,
      "includeInactive": boolean
    },
    "pausedReason": {
      "code": "bounce_rate" | "complaint_rate" | "workspace_guard" | "manual",
      "auto": boolean,
      "message": string,
      "at": string,
      "value": number,
      "threshold": number,
      "sample": number
    },
    "abTest": {
      "variants": [{ … }],
      "testPercent": number,
      "metric": "open" | "click" | "conversion" | "revenue",
      "durationHours": number,
      "winnerSelection": "auto" | "manual",
      "phase": "testing" | "waiting_for_pick" | "winner_sent" | null,
      "testStartedAt": string or null,
      "decideAt": string or null,
      "winnerId": 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`)

## Create a draft campaign

POST `/v1/campaigns`

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `name`required | `string` | Internal name, shown in lists and reports. |
| `subject` | `string` | Subject line. `{{variables}}` (contact fields such as `{{first_name}}`) are filled in per recipient. |
| `previewText` | `string or null` | Preview text shown after the subject in most inboxes. |
| `fromName` | `string` | Sender name, for example "Acme". |
| `fromEmail` | `string` | Sender address, for example news@acme.com. Its domain should be verified. |
| `replyTo` | `string or null` | Reply-To address. |
| `templateId` | `string or null` | Saved template to send. Its variables are filled from each contact; see `GET /v1/campaigns/{id}/check` for variables no contact field provides. |
| `html` | `string` | HTML content when not using a template. |
| `recipients` | `object` | Contacts in any of `listIds` or `segmentIds`, minus `excludeListIds`. Unsubscribed, bounced and suppressed contacts are skipped. |
| `recipients.listIds` | `array of string` | Default \[\]. |
| `recipients.segmentIds` | `array of string` | Default \[\]. |
| `recipients.excludeListIds` | `array of string` | Default \[\]. |
| `tracking` | `object` | Open and click tracking, and UTM parameters added to links. |
| `tracking.opens` | `boolean` |  |
| `tracking.clicks` | `boolean` |  |
| `tracking.utm` | `object or null` |  |
| `tracking.utm.source`required | `string` |  |
| `tracking.utm.medium`required | `string` |  |
| `tracking.utm.campaign`required | `string` |  |
| `currency` | `string` | ISO currency for revenue in reports, for example USD. |
| `tags` | `array of string` |  |
| `policyId` | `string or null` | Routing policy; defaults to the workspace default. |
| `delivery` | `object or null` | `bestTime`: send each email at the hour the recipient usually opens (within 24 hours of the start). `includeQualityIssues` and `includeInactive` include contacts that campaigns skip by default. |
| `delivery.bestTime` | `boolean` |  |
| `delivery.includeQualityIssues` | `boolean` |  |
| `delivery.includeInactive` | `boolean` |  |
| `abTest` | `object or null` | A/B test: 2 to 4 variants sent to a test group first; the winner goes to the rest. `null` turns it off. |
| `abTest.enabled` | `boolean` | `false` turns the test off (same as `abTest: null`). |
| `abTest.variants` | `array of object` | At most 4 items. |
| `abTest.variants[].id` | `string` | a, b, c or d (assigned in order). |
| `abTest.variants[].name` | `string or null` |  |
| `abTest.variants[].subject` | `string or null` |  |
| `abTest.variants[].previewText` | `string or null` |  |
| `abTest.variants[].fromName` | `string or null` |  |
| `abTest.variants[].templateId` | `string or null` |  |
| `abTest.variants[].html` | `string or null` |  |
| `abTest.testPercent` | `number` | Share of the recipients in the test group, split evenly between the variants. Default 20. 5 to 50. |
| `abTest.metric` | `"open" \| "click" \| "conversion" \| "revenue"` | How the winner is picked: open, click or conversion rate, or revenue per delivered email. Default open. |
| `abTest.durationHours` | `number` | How long the test group gets before the winner is picked. Default 4. 1 to 168. |
| `abTest.winnerSelection` | `"auto" \| "manual"` | `auto`: the leading variant is sent to the rest when the test ends. `manual`: the campaign waits for POST /v1/campaigns/{id}/ab-test/winner. |

### Responses

`201` Success

```
{
  "id": string,
  "object": "campaign",
  "name": string,
  "status": "draft" | "scheduled" | "sending" | "sent" | "paused" | "canceled" | "failed",
  "subject": string,
  "previewText": string or null,
  "fromName": string,
  "fromEmail": string,
  "replyTo": string or null,
  "templateId": string or null,
  "recipients": {
    "listIds": [string],
    "segmentIds": [string],
    "excludeListIds": [string]
  },
  "tracking": {
    "opens": boolean,
    "clicks": boolean,
    "utm": {
      "source": string,
      "medium": string,
      "campaign": string
    }
  },
  "currency": string,
  "tags": [string],
  "policyId": string or null,
  "scheduledAt": string or null,
  "sentAt": string or null,
  "estimatedRecipients": number or null,
  "plan": {
    "perDay": number,
    "days": number,
    "unlimited": boolean,
    "limitedBy": "quota" | "warmup" | "pacing",
    "reason": string,
    "domain": string
  },
  "delivery": {
    "bestTime": boolean,
    "includeQualityIssues": boolean,
    "includeInactive": boolean
  },
  "pausedReason": {
    "code": "bounce_rate" | "complaint_rate" | "workspace_guard" | "manual",
    "auto": boolean,
    "message": string,
    "at": string,
    "value": number,
    "threshold": number,
    "sample": number
  },
  "abTest": {
    "variants": [{
      "id": string,
      "name": string or null,
      "subject": string or null,
      "previewText": string or null,
      "fromName": 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`)

## Get a campaign

GET `/v1/campaigns/{id}`

Drafts include a live recipient estimate and sending plan; started campaigns include stats.

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

### Parameters

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

### Responses

`200` Success

```
{
  "id": string,
  "object": "campaign",
  "name": string,
  "status": "draft" | "scheduled" | "sending" | "sent" | "paused" | "canceled" | "failed",
  "subject": string,
  "previewText": string or null,
  "fromName": string,
  "fromEmail": string,
  "replyTo": string or null,
  "templateId": string or null,
  "recipients": {
    "listIds": [string],
    "segmentIds": [string],
    "excludeListIds": [string]
  },
  "tracking": {
    "opens": boolean,
    "clicks": boolean,
    "utm": {
      "source": string,
      "medium": string,
      "campaign": string
    }
  },
  "currency": string,
  "tags": [string],
  "policyId": string or null,
  "scheduledAt": string or null,
  "sentAt": string or null,
  "estimatedRecipients": number or null,
  "plan": {
    "perDay": number,
    "days": number,
    "unlimited": boolean,
    "limitedBy": "quota" | "warmup" | "pacing",
    "reason": string,
    "domain": string
  },
  "delivery": {
    "bestTime": boolean,
    "includeQualityIssues": boolean,
    "includeInactive": boolean
  },
  "pausedReason": {
    "code": "bounce_rate" | "complaint_rate" | "workspace_guard" | "manual",
    "auto": boolean,
    "message": string,
    "at": string,
    "value": number,
    "threshold": number,
    "sample": number
  },
  "abTest": {
    "variants": [{
      "id": string,
      "name": string or null,
      "subject": string or null,
      "previewText": string or null,
      "fromName": 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`)

## Edit a campaign

PATCH `/v1/campaigns/{id}`

Drafts and scheduled campaigns can be edited. Once sending has started only the name and tags can change.

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

### Parameters

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `name` | `string` | Internal name, shown in lists and reports. |
| `subject` | `string` | Subject line. `{{variables}}` (contact fields such as `{{first_name}}`) are filled in per recipient. |
| `previewText` | `string or null` | Preview text shown after the subject in most inboxes. |
| `fromName` | `string` | Sender name, for example "Acme". |
| `fromEmail` | `string` | Sender address, for example news@acme.com. Its domain should be verified. |
| `replyTo` | `string or null` | Reply-To address. |
| `templateId` | `string or null` | Saved template to send. Its variables are filled from each contact; see `GET /v1/campaigns/{id}/check` for variables no contact field provides. |
| `html` | `string` | HTML content when not using a template. |
| `recipients` | `object` | Contacts in any of `listIds` or `segmentIds`, minus `excludeListIds`. Unsubscribed, bounced and suppressed contacts are skipped. |
| `recipients.listIds` | `array of string` | Default \[\]. |
| `recipients.segmentIds` | `array of string` | Default \[\]. |
| `recipients.excludeListIds` | `array of string` | Default \[\]. |
| `tracking` | `object` | Open and click tracking, and UTM parameters added to links. |
| `tracking.opens` | `boolean` |  |
| `tracking.clicks` | `boolean` |  |
| `tracking.utm` | `object or null` |  |
| `tracking.utm.source`required | `string` |  |
| `tracking.utm.medium`required | `string` |  |
| `tracking.utm.campaign`required | `string` |  |
| `currency` | `string` | ISO currency for revenue in reports, for example USD. |
| `tags` | `array of string` |  |
| `policyId` | `string or null` | Routing policy; defaults to the workspace default. |
| `delivery` | `object or null` | `bestTime`: send each email at the hour the recipient usually opens (within 24 hours of the start). `includeQualityIssues` and `includeInactive` include contacts that campaigns skip by default. |
| `delivery.bestTime` | `boolean` |  |
| `delivery.includeQualityIssues` | `boolean` |  |
| `delivery.includeInactive` | `boolean` |  |
| `abTest` | `object or null` | A/B test: 2 to 4 variants sent to a test group first; the winner goes to the rest. `null` turns it off. |
| `abTest.enabled` | `boolean` | `false` turns the test off (same as `abTest: null`). |
| `abTest.variants` | `array of object` | At most 4 items. |
| `abTest.variants[].id` | `string` | a, b, c or d (assigned in order). |
| `abTest.variants[].name` | `string or null` |  |
| `abTest.variants[].subject` | `string or null` |  |
| `abTest.variants[].previewText` | `string or null` |  |
| `abTest.variants[].fromName` | `string or null` |  |
| `abTest.variants[].templateId` | `string or null` |  |
| `abTest.variants[].html` | `string or null` |  |
| `abTest.testPercent` | `number` | Share of the recipients in the test group, split evenly between the variants. Default 20. 5 to 50. |
| `abTest.metric` | `"open" \| "click" \| "conversion" \| "revenue"` | How the winner is picked: open, click or conversion rate, or revenue per delivered email. Default open. |
| `abTest.durationHours` | `number` | How long the test group gets before the winner is picked. Default 4. 1 to 168. |
| `abTest.winnerSelection` | `"auto" \| "manual"` | `auto`: the leading variant is sent to the rest when the test ends. `manual`: the campaign waits for POST /v1/campaigns/{id}/ab-test/winner. |

### Responses

`200` Success

```
{
  "id": string,
  "object": "campaign",
  "name": string,
  "status": "draft" | "scheduled" | "sending" | "sent" | "paused" | "canceled" | "failed",
  "subject": string,
  "previewText": string or null,
  "fromName": string,
  "fromEmail": string,
  "replyTo": string or null,
  "templateId": string or null,
  "recipients": {
    "listIds": [string],
    "segmentIds": [string],
    "excludeListIds": [string]
  },
  "tracking": {
    "opens": boolean,
    "clicks": boolean,
    "utm": {
      "source": string,
      "medium": string,
      "campaign": string
    }
  },
  "currency": string,
  "tags": [string],
  "policyId": string or null,
  "scheduledAt": string or null,
  "sentAt": string or null,
  "estimatedRecipients": number or null,
  "plan": {
    "perDay": number,
    "days": number,
    "unlimited": boolean,
    "limitedBy": "quota" | "warmup" | "pacing",
    "reason": string,
    "domain": string
  },
  "delivery": {
    "bestTime": boolean,
    "includeQualityIssues": boolean,
    "includeInactive": boolean
  },
  "pausedReason": {
    "code": "bounce_rate" | "complaint_rate" | "workspace_guard" | "manual",
    "auto": boolean,
    "message": string,
    "at": string,
    "value": number,
    "threshold": number,
    "sample": number
  },
  "abTest": {
    "variants": [{
      "id": string,
      "name": string or null,
      "subject": string or null,
      "previewText": string or null,
      "fromName": 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`)

## Delete a campaign

DELETE `/v1/campaigns/{id}`

A campaign that is sending must be paused or canceled first. Emails already sent stay in the logs and stay viewable: the campaign disappears from the API, but what is needed to show those emails is kept.

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

### Parameters

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

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

## Check a campaign before sending

GET `/v1/campaigns/{id}/check`

What would stop the campaign from being scheduled (`problems`), and template `{{variables}}` that no contact provides (`missingVariables`). Show these in a review step before sending.

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

### Parameters

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

### Responses

`200` Success

```
{
  "ready": boolean,
  "problems": [string],
  "missingVariables": [{
    "path": string,
    "usedIn": ["subject" | "preheader" | "content"]
  }],
  "warnings": [{
    "code": "missing_variables" | "transactional_template",
    "message": string,
    "variables": [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`)

## Duplicate as a new draft

POST `/v1/campaigns/{id}/duplicate`

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

### Parameters

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

### Responses

`201` Success

```
{
  "id": string,
  "object": "campaign",
  "name": string,
  "status": "draft" | "scheduled" | "sending" | "sent" | "paused" | "canceled" | "failed",
  "subject": string,
  "previewText": string or null,
  "fromName": string,
  "fromEmail": string,
  "replyTo": string or null,
  "templateId": string or null,
  "recipients": {
    "listIds": [string],
    "segmentIds": [string],
    "excludeListIds": [string]
  },
  "tracking": {
    "opens": boolean,
    "clicks": boolean,
    "utm": {
      "source": string,
      "medium": string,
      "campaign": string
    }
  },
  "currency": string,
  "tags": [string],
  "policyId": string or null,
  "scheduledAt": string or null,
  "sentAt": string or null,
  "estimatedRecipients": number or null,
  "plan": {
    "perDay": number,
    "days": number,
    "unlimited": boolean,
    "limitedBy": "quota" | "warmup" | "pacing",
    "reason": string,
    "domain": string
  },
  "delivery": {
    "bestTime": boolean,
    "includeQualityIssues": boolean,
    "includeInactive": boolean
  },
  "pausedReason": {
    "code": "bounce_rate" | "complaint_rate" | "workspace_guard" | "manual",
    "auto": boolean,
    "message": string,
    "at": string,
    "value": number,
    "threshold": number,
    "sample": number
  },
  "abTest": {
    "variants": [{
      "id": string,
      "name": string or null,
      "subject": string or null,
      "previewText": string or null,
      "fromName": 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`)

## Send a test email

POST `/v1/campaigns/{id}/test`

Sent through your routing policy like a real send, with "\[Test\]" in the subject. Not counted in campaign stats.

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

### Parameters

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `to`required | `array of string (email)` | At most 5 items. |

### Responses

`202` Success

```
{
  "messageIds": [string]
}
```

**Errors: 400, 401, 402, 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`.
- `402` Payment required (type `payment_required`): `license_required`, a self-hosted server without an active license key (`details.buyUrl`); on the cloud, only when cloud plans are enabled, `plan_required` (the workspace has no plan; `details.upgradeUrl`).
- `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`)

## Schedule, or send now

POST `/v1/campaigns/{id}/schedule`

`scheduledAt: null` sends now. Recipients are fixed when sending starts. When the audience is larger than today’s remaining quota on providers that allow campaigns, the rest is sent on the following days. Not available to test-mode keys.

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

### Parameters

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `scheduledAt`required | `string or null` |  |
| `bestTime` | `boolean` | Send each email at the recipient's best time within 24 hours of `scheduledAt` (or now). Saved as `delivery.bestTime`. |

### Responses

`202` Success

```
{
  "id": string,
  "object": "campaign",
  "name": string,
  "status": "draft" | "scheduled" | "sending" | "sent" | "paused" | "canceled" | "failed",
  "subject": string,
  "previewText": string or null,
  "fromName": string,
  "fromEmail": string,
  "replyTo": string or null,
  "templateId": string or null,
  "recipients": {
    "listIds": [string],
    "segmentIds": [string],
    "excludeListIds": [string]
  },
  "tracking": {
    "opens": boolean,
    "clicks": boolean,
    "utm": {
      "source": string,
      "medium": string,
      "campaign": string
    }
  },
  "currency": string,
  "tags": [string],
  "policyId": string or null,
  "scheduledAt": string or null,
  "sentAt": string or null,
  "estimatedRecipients": number or null,
  "plan": {
    "perDay": number,
    "days": number,
    "unlimited": boolean,
    "limitedBy": "quota" | "warmup" | "pacing",
    "reason": string,
    "domain": string
  },
  "delivery": {
    "bestTime": boolean,
    "includeQualityIssues": boolean,
    "includeInactive": boolean
  },
  "pausedReason": {
    "code": "bounce_rate" | "complaint_rate" | "workspace_guard" | "manual",
    "auto": boolean,
    "message": string,
    "at": string,
    "value": number,
    "threshold": number,
    "sample": number
  },
  "abTest": {
    "variants": [{
      "id": string,
      "name": string or null,
      "subject": string or null,
      "previewText": string or null,
      "fromName": string or null,
  …
```

**Errors: 400, 401, 402, 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`.
- `402` Payment required (type `payment_required`): `license_required`, a self-hosted server without an active license key (`details.buyUrl`); on the cloud, only when cloud plans are enabled, `plan_required` (the workspace has no plan; `details.upgradeUrl`).
- `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`)

## Pause sending (emails not yet handed to a provider are held)

POST `/v1/campaigns/{id}/pause`

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

### Parameters

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

### Responses

`200` Success

```
{
  "id": string,
  "object": "campaign",
  "name": string,
  "status": "draft" | "scheduled" | "sending" | "sent" | "paused" | "canceled" | "failed",
  "subject": string,
  "previewText": string or null,
  "fromName": string,
  "fromEmail": string,
  "replyTo": string or null,
  "templateId": string or null,
  "recipients": {
    "listIds": [string],
    "segmentIds": [string],
    "excludeListIds": [string]
  },
  "tracking": {
    "opens": boolean,
    "clicks": boolean,
    "utm": {
      "source": string,
      "medium": string,
      "campaign": string
    }
  },
  "currency": string,
  "tags": [string],
  "policyId": string or null,
  "scheduledAt": string or null,
  "sentAt": string or null,
  "estimatedRecipients": number or null,
  "plan": {
    "perDay": number,
    "days": number,
    "unlimited": boolean,
    "limitedBy": "quota" | "warmup" | "pacing",
    "reason": string,
    "domain": string
  },
  "delivery": {
    "bestTime": boolean,
    "includeQualityIssues": boolean,
    "includeInactive": boolean
  },
  "pausedReason": {
    "code": "bounce_rate" | "complaint_rate" | "workspace_guard" | "manual",
    "auto": boolean,
    "message": string,
    "at": string,
    "value": number,
    "threshold": number,
    "sample": number
  },
  "abTest": {
    "variants": [{
      "id": string,
      "name": string or null,
      "subject": string or null,
      "previewText": string or null,
      "fromName": 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`)

## Resume a paused campaign

POST `/v1/campaigns/{id}/resume`

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

### Parameters

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

### Responses

`200` Success

```
{
  "id": string,
  "object": "campaign",
  "name": string,
  "status": "draft" | "scheduled" | "sending" | "sent" | "paused" | "canceled" | "failed",
  "subject": string,
  "previewText": string or null,
  "fromName": string,
  "fromEmail": string,
  "replyTo": string or null,
  "templateId": string or null,
  "recipients": {
    "listIds": [string],
    "segmentIds": [string],
    "excludeListIds": [string]
  },
  "tracking": {
    "opens": boolean,
    "clicks": boolean,
    "utm": {
      "source": string,
      "medium": string,
      "campaign": string
    }
  },
  "currency": string,
  "tags": [string],
  "policyId": string or null,
  "scheduledAt": string or null,
  "sentAt": string or null,
  "estimatedRecipients": number or null,
  "plan": {
    "perDay": number,
    "days": number,
    "unlimited": boolean,
    "limitedBy": "quota" | "warmup" | "pacing",
    "reason": string,
    "domain": string
  },
  "delivery": {
    "bestTime": boolean,
    "includeQualityIssues": boolean,
    "includeInactive": boolean
  },
  "pausedReason": {
    "code": "bounce_rate" | "complaint_rate" | "workspace_guard" | "manual",
    "auto": boolean,
    "message": string,
    "at": string,
    "value": number,
    "threshold": number,
    "sample": number
  },
  "abTest": {
    "variants": [{
      "id": string,
      "name": string or null,
      "subject": string or null,
      "previewText": string or null,
      "fromName": 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`)

## Cancel (emails not yet handed to a provider are dropped)

POST `/v1/campaigns/{id}/cancel`

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

### Parameters

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

### Responses

`200` Success

```
{
  "id": string,
  "object": "campaign",
  "name": string,
  "status": "draft" | "scheduled" | "sending" | "sent" | "paused" | "canceled" | "failed",
  "subject": string,
  "previewText": string or null,
  "fromName": string,
  "fromEmail": string,
  "replyTo": string or null,
  "templateId": string or null,
  "recipients": {
    "listIds": [string],
    "segmentIds": [string],
    "excludeListIds": [string]
  },
  "tracking": {
    "opens": boolean,
    "clicks": boolean,
    "utm": {
      "source": string,
      "medium": string,
      "campaign": string
    }
  },
  "currency": string,
  "tags": [string],
  "policyId": string or null,
  "scheduledAt": string or null,
  "sentAt": string or null,
  "estimatedRecipients": number or null,
  "plan": {
    "perDay": number,
    "days": number,
    "unlimited": boolean,
    "limitedBy": "quota" | "warmup" | "pacing",
    "reason": string,
    "domain": string
  },
  "delivery": {
    "bestTime": boolean,
    "includeQualityIssues": boolean,
    "includeInactive": boolean
  },
  "pausedReason": {
    "code": "bounce_rate" | "complaint_rate" | "workspace_guard" | "manual",
    "auto": boolean,
    "message": string,
    "at": string,
    "value": number,
    "threshold": number,
    "sample": number
  },
  "abTest": {
    "variants": [{
      "id": string,
      "name": string or null,
      "subject": string or null,
      "previewText": string or null,
      "fromName": 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`)

## A/B test results

GET `/v1/campaigns/{id}/ab-test`

Results per variant, the leader and whether the difference is likely to be chance (two-proportion z-test, 95%).

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

### Parameters

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

### Responses

`200` Success

```
{
  "metric": "open" | "click" | "conversion" | "revenue",
  "testPercent": number,
  "durationHours": number,
  "winnerSelection": "auto" | "manual",
  "phase": string or null,
  "testStartedAt": string or null,
  "decideAt": string or null,
  "winnerId": string or null,
  "decidedAt": string or null,
  "decidedBy": string or null,
  "held": number,
  "variants": [{
    "id": string,
    "name": string,
    "subject": string or null,
    "recipients": number,
    "sent": number,
    "delivered": number,
    "uniqueOpens": number,
    "uniqueClicks": number,
    "conversions": number,
    "revenue": number,
    "rates": {
      "open": number,
      "click": number,
      "conversion": number,
      "revenuePerEmail": number
    },
    "value": number,
    "success": number,
    "winner": boolean
  }],
  "leader": string or null,
  "comparison": {
    "leader": string,
    "runnerUp": string,
    "z": number,
    "pValue": number,
    "significant": boolean
  },
  "summary": 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`)

## Pick the A/B test winner

POST `/v1/campaigns/{id}/ab-test/winner`

Sends the winning variant to the rest of the recipients now. Needed when `winnerSelection` is `manual`; with `auto` it ends the test early.

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

### Parameters

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `variantId`required | `string` |  |

### Responses

`200` Success

```
{
  "metric": "open" | "click" | "conversion" | "revenue",
  "testPercent": number,
  "durationHours": number,
  "winnerSelection": "auto" | "manual",
  "phase": string or null,
  "testStartedAt": string or null,
  "decideAt": string or null,
  "winnerId": string or null,
  "decidedAt": string or null,
  "decidedBy": string or null,
  "held": number,
  "variants": [{
    "id": string,
    "name": string,
    "subject": string or null,
    "recipients": number,
    "sent": number,
    "delivered": number,
    "uniqueOpens": number,
    "uniqueClicks": number,
    "conversions": number,
    "revenue": number,
    "rates": {
      "open": number,
      "click": number,
      "conversion": number,
      "revenuePerEmail": number
    },
    "value": number,
    "success": number,
    "winner": boolean
  }],
  "leader": string or null,
  "comparison": {
    "leader": string,
    "runnerUp": string,
    "z": number,
    "pValue": number,
    "significant": boolean
  },
  "summary": string
}
```

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

## Campaign report

GET `/v1/campaigns/{id}/report`

Rates: delivery = delivered/sent · open = unique opens/delivered · click = unique clicks/delivered · click-to-open = unique clicks/unique opens · bounce = (hard+soft)/sent · unsubscribe, complaint and conversion = count/delivered. "Delivered" is accepted by the provider and not bounced. Conversions count recipients who converted at least once; revenue sums every conversion.

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

### Parameters

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

### Responses

`200` Success

```
{
  "campaign": {
    "id": string,
    "object": "campaign",
    "name": string,
    "status": "draft" | "scheduled" | "sending" | "sent" | "paused" | "canceled" | "failed",
    "subject": string,
    "previewText": string or null,
    "fromName": string,
    "fromEmail": string,
    "replyTo": string or null,
    "templateId": string or null,
    "recipients": {
      "listIds": [string],
      "segmentIds": [string],
      "excludeListIds": [string]
    },
    "tracking": {
      "opens": boolean,
      "clicks": boolean,
      "utm": {
        "source": string,
        "medium": string,
        "campaign": string
      }
    },
    "currency": string,
    "tags": [string],
    "policyId": string or null,
    "scheduledAt": string or null,
    "sentAt": string or null,
    "estimatedRecipients": number or null,
    "plan": {
      "perDay": number,
      "days": number,
      "unlimited": boolean,
      "limitedBy": "quota" | "warmup" | "pacing",
      "reason": string,
      "domain": string
    },
    "delivery": {
      "bestTime": boolean,
      "includeQualityIssues": boolean,
      "includeInactive": boolean
    },
    "pausedReason": {
      "code": "bounce_rate" | "complaint_rate" | "workspace_guard" | "manual",
      "auto": boolean,
      "message": string,
      "at": string,
      "value": number,
      "threshold": number,
      "sample": number
    },
    "abTest": {
      "variants": [{ … }],
      "testPercent": number,
      "metric": "open" | "click" | "conversion" | "revenue",
      "durationHours": number,
      "winnerSelection": "auto" | "manual",
  …
```

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

## Recipient activity (JSON or CSV)

GET `/v1/campaigns/{id}/recipients`

`cursor` is a row offset: pass back `nextCursor` unchanged. `format=csv` returns every matching row as a file.

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

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |
| `cursor` | query | `string` |  |
| `limit` | query | `integer` | Default 100. 1 to 500. |
| `filter` | query | `"all" \| "delivered" \| "opened" \| "clicked" \| "bounced" \| "unsubscribed" \| "complained" \| "converted" \| "not_opened"` | Default "all". |
| `q` | query | `string` |  |
| `format` | query | `"json" \| "csv"` | Default "json". |

### Responses

`200` Success

```
{
  "data": [{
    "contactId": string or null,
    "connectionId": string or null,
    "connectionName": string or null,
    "email": string,
    "messageId": string or null,
    "status": string,
    "provider": string or null,
    "openedAt": string or null,
    "clickedAt": string or null,
    "convertedAt": string or null,
    "bounceType": "hard" | "soft" | null
  }],
  "nextCursor": string or null,
  "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`)

## Safeguards that apply to a campaign

GET `/v1/campaigns/{id}/safeguards`

For the review step: the automatic pause thresholds, warm-up and pacing of the sending domain and the combined sending plan, contacts left out for address problems or inactivity, the workspace guard and the best time to send.

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

### Parameters

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

### Responses

`200` Success

```
{
  "items": [{
    "code": string,
    "title": string,
    "detail": string,
    "level": "info" | "warning" | "blocking"
  }],
  "plan": {
    "perDay": number,
    "days": number,
    "unlimited": boolean,
    "limitedBy": string,
    "reason": string
  },
  "excluded": {
    "quality": number,
    "inactive": number
  },
  "guard": {
    "blocked": boolean,
    "code": string or null,
    "message": string or null,
    "blockedAt": string or null,
    "acknowledgedAt": string or null,
    "bounceRate": number,
    "complaintRate": number,
    "sample": number
  },
  "bestTime": {
    "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`)
