---
title: "AI assistant API"
description: "AI assistant in the OneSend API: 23 endpoints. Method, path, parameters, request body and response shape for each."
url: https://onesend.email/docs/api-reference/ai-assistant/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/docs/api-reference/)

# AI assistant

Optional assistant that uses your own model provider key: summaries, reply drafts, subject lines, template generation, rewriting, triage suggestions and questions about your inbox. Off until turned on; suggestions are never applied automatically.

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

## AI settings

GET `/v1/ai/settings`

Whether the assistant is on, the default model connection, the brand voice (writing profile) and the privacy settings (what may be sent to the model provider). The assistant is off until turned on.

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

### Responses

`200` Success

```
{
  "enabled": boolean,
  "defaultConnectionId": string or null,
  "writingProfile": {
    "styleNotes": string,
    "signOff": string
  },
  "privacy": {
    "brandVoice": boolean,
    "facts": boolean,
    "providerResponses": boolean,
    "recipientDomains": boolean,
    "domainNames": boolean
  },
  "logPrompts": boolean,
  "rateLimitPerMinute": 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`)

## Update AI settings

PATCH `/v1/ai/settings`

Turn the assistant on or off, choose the default connection, edit the brand voice (writing profile) and the privacy settings. Admins only.

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `enabled` | `boolean` |  |
| `defaultConnectionId` | `string or null` |  |
| `writingProfile` | `object` |  |
| `writingProfile.styleNotes` | `string` | How you write: tone, length, words to avoid. Included in drafting prompts. |
| `writingProfile.signOff` | `string` | Added at the end of drafted replies, for example "Thanks,\nAda". |
| `privacy` | `object` |  |
| `privacy.brandVoice` | `boolean` | Include the brand voice (style notes and sign-off) in prompts. Default true. |
| `privacy.facts` | `boolean` | Include matching facts (workspace notes) in prompts. Default true. |
| `privacy.providerResponses` | `boolean` | Send provider and SMTP error text (with addresses removed) when explaining a failed email. Off: only codes are sent. Default true. |
| `privacy.recipientDomains` | `boolean` | Send the recipient's domain (for example gmail.com) when explaining a failed email. Default true. |
| `privacy.domainNames` | `boolean` | Send your sending domain and provider connection names. Off: they are replaced with placeholders such as "domain 1". Default true. |

### Responses

`200` Success

```
{
  "enabled": boolean,
  "defaultConnectionId": string or null,
  "writingProfile": {
    "styleNotes": string,
    "signOff": string
  },
  "privacy": {
    "brandVoice": boolean,
    "facts": boolean,
    "providerResponses": boolean,
    "recipientDomains": boolean,
    "domainNames": boolean
  },
  "logPrompts": boolean,
  "rateLimitPerMinute": 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`)

## List AI connections

GET `/v1/ai/connections`

Model provider connections. API keys are never returned; `keyHint` shows the last characters.

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

### Responses

`200` Success

```
{
  "data": [{
    "id": string,
    "object": "ai_connection",
    "name": string,
    "kind": "openai_compatible" | "anthropic" | "google",
    "model": string,
    "baseUrl": string or null,
    "authHeader": "bearer" | "api-key",
    "apiVersion": string or null,
    "keyHint": string or null,
    "isDefault": boolean,
    "status": "untested" | "ok" | "error",
    "lastError": string or null,
    "lastTestedAt": string or null,
    "createdAt": string,
    "updatedAt": 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`)

## Add an AI connection

POST `/v1/ai/connections`

`openai_compatible` needs `baseUrl` (OpenAI, Azure OpenAI, API gateways, or a local server such as Ollama at http://localhost:11434/v1). `anthropic` and `google` need `apiKey`. The key is encrypted at rest. Prompt content goes to the provider you choose; usage is billed by that provider.

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `name`required | `string` |  |
| `kind`required | `"openai_compatible" \| "anthropic" \| "google"` |  |
| `model`required | `string` | Model id as the provider names it. |
| `apiKey` | `string` | Encrypted at rest and never returned. Optional for local OpenAI-compatible servers such as Ollama. |
| `baseUrl` | `string (uri)` | Required for `openai_compatible`. Optional for `anthropic` and `google` (an API gateway). Private and loopback addresses need ONESEND\_ALLOW\_PRIVATE\_NETWORK=true. |
| `authHeader` | `"bearer" \| "api-key"` | openai\_compatible only. Default `bearer`. |
| `apiVersion` | `string` | openai\_compatible: sent as the `api-version` query parameter (Azure). anthropic: the `anthropic-version` header (default 2023-06-01). |
| `makeDefault` | `boolean` | Use this connection when a request does not name one. The first connection becomes the default. |

### Responses

`201` Success

```
{
  "id": string,
  "object": "ai_connection",
  "name": string,
  "kind": "openai_compatible" | "anthropic" | "google",
  "model": string,
  "baseUrl": string or null,
  "authHeader": "bearer" | "api-key",
  "apiVersion": string or null,
  "keyHint": string or null,
  "isDefault": boolean,
  "status": "untested" | "ok" | "error",
  "lastError": string or null,
  "lastTestedAt": string or null,
  "createdAt": string,
  "updatedAt": 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`)

## Get an AI connection

GET `/v1/ai/connections/{id}`

**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": "ai_connection",
  "name": string,
  "kind": "openai_compatible" | "anthropic" | "google",
  "model": string,
  "baseUrl": string or null,
  "authHeader": "bearer" | "api-key",
  "apiVersion": string or null,
  "keyHint": string or null,
  "isDefault": boolean,
  "status": "untested" | "ok" | "error",
  "lastError": string or null,
  "lastTestedAt": string or null,
  "createdAt": string,
  "updatedAt": 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`)

## Update an AI connection

PATCH `/v1/ai/connections/{id}`

**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` |  |
| `model` | `string` |  |
| `apiKey` | `string` | Replaces the stored key. Send an empty string to remove it. |
| `baseUrl` | `string (uri) or null` |  |
| `authHeader` | `"bearer" \| "api-key"` |  |
| `apiVersion` | `string or null` |  |
| `makeDefault` | `boolean` |  |

### Responses

`200` Success

```
{
  "id": string,
  "object": "ai_connection",
  "name": string,
  "kind": "openai_compatible" | "anthropic" | "google",
  "model": string,
  "baseUrl": string or null,
  "authHeader": "bearer" | "api-key",
  "apiVersion": string or null,
  "keyHint": string or null,
  "isDefault": boolean,
  "status": "untested" | "ok" | "error",
  "lastError": string or null,
  "lastTestedAt": string or null,
  "createdAt": string,
  "updatedAt": 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`)

## Delete an AI connection

DELETE `/v1/ai/connections/{id}`

The stored key is deleted. When it was the default, the oldest remaining connection is used.

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

## Test an AI connection

POST `/v1/ai/connections/{id}/test`

Sends a short prompt to the model and reports whether it answered. Works while the assistant is turned off.

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

### Parameters

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

### Responses

`200` Success

```
{
  "ok": boolean,
  "model": string,
  "latencyMs": number,
  "sample": string or null,
  "error": {
    "code": string,
    "message": string
  }
}
```

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

## List workspace notes

GET `/v1/ai/notes`

Facts the AI can use: short notes (policies, product facts, prices) included in drafts, templates, rewrites, answers and explanations when they match the topic (up to 3 notes and 4,000 characters per prompt). The privacy setting `facts` turns this off.

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

### Responses

`200` Success

```
{
  "data": [{
    "id": string,
    "object": "ai_note",
    "title": string,
    "text": string,
    "createdAt": string,
    "updatedAt": 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`)

## Add a note

POST `/v1/ai/notes`

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `title`required | `string` |  |
| `text`required | `string` |  |

### Responses

`201` Success

```
{
  "id": string,
  "object": "ai_note",
  "title": string,
  "text": string,
  "createdAt": string,
  "updatedAt": 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`)

## Get a note

GET `/v1/ai/notes/{id}`

**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": "ai_note",
  "title": string,
  "text": string,
  "createdAt": string,
  "updatedAt": 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`)

## Update a note

PATCH `/v1/ai/notes/{id}`

**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 |
|---|---|---|
| `title` | `string` |  |
| `text` | `string` |  |

### Responses

`200` Success

```
{
  "id": string,
  "object": "ai_note",
  "title": string,
  "text": string,
  "createdAt": string,
  "updatedAt": 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`)

## Delete a note

DELETE `/v1/ai/notes/{id}`

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

## AI usage

GET `/v1/ai/usage`

Model calls and token counts per day, feature and model (tokens only when the provider reports them). Costs are billed by your model provider.

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

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `days` | query | `integer` | Default 30. 1 to 90. |

### Responses

`200` Success

```
{
  "days": number,
  "totals": {
    "calls": number,
    "errors": number,
    "inputTokens": number,
    "outputTokens": number
  },
  "data": [{
    "day": string,
    "feature": "test" | "summarize" | "draft_reply" | "subjects" | "generate_template" | "rewrite" | "triage" | "ask" | "explain_failure" | "deliverability_review" | …,
    "connectionId": string or null,
    "model": string or null,
    "calls": number,
    "errors": number,
    "inputTokens": number,
    "outputTokens": 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`)

## Summarize a thread

POST `/v1/ai/summarize`

Bullet summary and action items for an inbox thread, a received message's thread, or a sent email with its replies. The thread content is sent to the model provider. Returns 403 `ai_disabled` while the assistant is turned off and 400 `ai_not_configured` without a connection.

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `threadId` | `string` | An inbox thread (received and sent messages). |
| `messageId` | `string` | A received message (`inb_` inbox id); its thread is summarized. |
| `emailId` | `string` | A sent email; it is summarized with the replies in its thread. |
| `connectionId` | `string` | AI connection to use. Defaults to the workspace default. |

### Responses

`200` Success

```
{
  "summary": [string],
  "actionItems": [{
    "text": string,
    "owner": string or null,
    "due": string or null
  }],
  "sources": [{
    "id": string,
    "kind": "inbound" | "sent",
    "threadId": string or null,
    "subject": string,
    "from": string,
    "at": string,
    "link": string
  }],
  "usage": {
    "connectionId": string,
    "model": string,
    "inputTokens": number or null,
    "outputTokens": number or null,
    "latencyMs": 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`)

## Suggest subject lines and preview text

POST `/v1/ai/subjects`

Suggestions from the email content or a topic. Returns 403 `ai_disabled` while the assistant is turned off and 400 `ai_not_configured` without a connection.

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `body` | `string` | The email content (text or HTML). |
| `topic` | `string` | What the email is about, when there is no body yet. |
| `currentSubject` | `string` |  |
| `kind` | `"subject" \| "preview" \| "both"` | Default "both". |
| `count` | `integer` | Default 5. 1 to 10. |
| `connectionId` | `string` | AI connection to use. Defaults to the workspace default. |

### Responses

`200` Success

```
{
  "subjects": [string],
  "previewTexts": [string],
  "context": {
    "brandVoice": boolean,
    "facts": [string]
  },
  "usage": {
    "connectionId": string,
    "model": string,
    "inputTokens": number or null,
    "outputTokens": number or null,
    "latencyMs": 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`)

## Generate a template

POST `/v1/ai/generate-template`

Returns a template document (blocks) from a description. The document is validated; when the first answer is not valid the model is asked once more. Raw HTML blocks are removed. Nothing is saved. Returns 403 `ai_disabled` while the assistant is turned off and 400 `ai_not_configured` without a connection.

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `prompt`required | `string` | For example "Order shipped notification with tracking button and order summary table". |
| `type` | `"transactional" \| "broadcast"` | Default "transactional". |
| `brand` | `object` |  |
| `brand.primary` | `string` |  |
| `brand.accent` | `string` |  |
| `brand.logoUrl` | `string` |  |
| `brand.companyName` | `string` |  |
| `connectionId` | `string` | AI connection to use. Defaults to the workspace default. |

### Responses

`200` Success

```
{
  "document": object,
  "subject": string,
  "preheader": string,
  "variables": [string],
  "warnings": [string],
  "attempts": number,
  "context": {
    "brandVoice": boolean,
    "facts": [string]
  },
  "usage": {
    "connectionId": string,
    "model": string,
    "inputTokens": number or null,
    "outputTokens": number or null,
    "latencyMs": 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`)

## Rewrite text

POST `/v1/ai/rewrite`

Shorter, clearer, friendlier, more formal, grammar fixes, translation or a custom instruction. Returns 403 `ai_disabled` while the assistant is turned off and 400 `ai_not_configured` without a connection.

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `text`required | `string` |  |
| `mode`required | `"shorter" \| "clearer" \| "friendlier" \| "more_formal" \| "fix_grammar" \| "translate" \| "custom"` |  |
| `language` | `string` | Required for `translate`, for example "German". |
| `instruction` | `string` | Required for `custom`. |
| `connectionId` | `string` | AI connection to use. Defaults to the workspace default. |

### Responses

`200` Success

```
{
  "text": string,
  "context": {
    "brandVoice": boolean,
    "facts": [string]
  },
  "usage": {
    "connectionId": string,
    "model": string,
    "inputTokens": number or null,
    "outputTokens": number or null,
    "latencyMs": 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`)

## Explain a failed email

POST `/v1/ai/explain-failure`

For a bounced, failed, deferred, complained or suppressed email: rule-based hints for known codes (550 5.1.1 user unknown, SPF and DKIM failures, DMARC rejections, full mailboxes, provider limits and rate limits, blocklists), the SMTP codes, the sending domain's DNS status, and links to the settings that fix it. The model gets codes, provider messages with addresses removed and the domain status; never the recipient address, the subject or the content. The rule-based part is returned also while the assistant is off; `ai.status` says whether the model added its wording (`ok`, `not_requested`, `disabled`, `not_configured`, `rate_limited`, `error`). Prompts include the brand voice and matching facts (workspace notes) unless the privacy settings leave them out.

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `emailId`required | `string` | A sent email (`msg_` id). |
| `useAi` | `boolean` | Ask the model to word the result. The rule-based part is returned either way, also while the assistant is off. Default true. |
| `language` | `string` | Language of the AI wording, for example "German". Default: English for explanations, the content's language for copy. |
| `connectionId` | `string` | AI connection to use. Defaults to the workspace default. |

### Responses

`200` Success

```
{
  "emailId": string,
  "status": string,
  "summary": string,
  "hints": [{
    "code": string,
    "severity": "error" | "warning" | "info",
    "title": string,
    "explanation": string,
    "actions": [string],
    "links": [{ … }],
    "retryable": boolean
  }],
  "facts": {
    "provider": string or null,
    "connectionId": string or null,
    "smtpCode": string or null,
    "enhancedCode": string or null,
    "httpStatus": number or null,
    "errorCode": string or null,
    "recipientDomain": string or null,
    "mailboxProvider": string or null,
    "sendingDomain": string or null,
    "domain": {
      "id": string,
      "name": string,
      "status": string,
      "spf": "ok" | "missing" | "mismatch" | "pending" | "not_needed" | "unknown",
      "dkim": "ok" | "missing" | "mismatch" | "pending" | "not_needed" | "unknown",
      "dmarc": "ok" | "missing" | "mismatch" | "pending" | "not_needed" | "unknown",
      "returnPath": "ok" | "missing" | "mismatch" | "pending" | "not_needed" | "unknown",
      "dmarcPolicy": string or null
    },
    "attempts": number,
    "events": [string]
  },
  "ai": {
    "status": "ok" | "not_requested" | "disabled" | "not_configured" | "rate_limited" | "error",
    "message": string or null,
    "usage": {
      "connectionId": string,
      "model": string,
      "inputTokens": number or null,
      "outputTokens": number or null,
      "latencyMs": number
    },
    "explanation": string or null,
    "steps": [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`)

## Review deliverability

POST `/v1/ai/deliverability-review`

A prioritized list of fixes from the workspace's DNS and authentication status per domain (SPF, DKIM, DMARC, alignment), bounce and complaint rates overall and per provider, suppression growth, warm-up and webhook health. Checks for data this server does not record are listed in `skipped`. Only aggregates are sent to the model. The rule-based part is returned also while the assistant is off; `ai.status` says whether the model added its wording (`ok`, `not_requested`, `disabled`, `not_configured`, `rate_limited`, `error`). Prompts include the brand voice and matching facts (workspace notes) unless the privacy settings leave them out.

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `days` | `integer` | Window for bounce, complaint and suppression rates. Default 30. 1 to 90. |
| `useAi` | `boolean` | Ask the model to word the result. The rule-based part is returned either way, also while the assistant is off. Default true. |
| `language` | `string` | Language of the AI wording, for example "German". Default: English for explanations, the content's language for copy. |
| `connectionId` | `string` | AI connection to use. Defaults to the workspace default. |

### Responses

`200` Success

```
{
  "checkedAt": string,
  "days": number,
  "findings": [{
    "code": string,
    "priority": "high" | "medium" | "low",
    "area": "authentication" | "bounces" | "complaints" | "providers" | "suppressions" | "warmup" | "webhooks" | "setup",
    "title": string,
    "detail": string,
    "fix": string,
    "links": [{ … }],
    "domain": string or null,
    "connectionId": string or null,
    "aiText": string or null
  }],
  "passed": [{
    "code": string,
    "title": string
  }],
  "stats": {
    "sent": number,
    "bounceRate": number,
    "complaintRate": number,
    "domains": number,
    "providers": number,
    "suppressions": {
      "total": number,
      "addedLast7Days": number,
      "addedPrevious7Days": number
    }
  },
  "skipped": [string],
  "ai": {
    "status": "ok" | "not_requested" | "disabled" | "not_configured" | "rate_limited" | "error",
    "message": string or null,
    "usage": {
      "connectionId": string,
      "model": string,
      "inputTokens": number or null,
      "outputTokens": number or null,
      "latencyMs": number
    },
    "summary": 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`)

## Check content for spam before sending

POST `/v1/ai/spam-check`

The content check (spammy phrases, image-to-text ratio, URL shorteners, all-caps subjects, missing unsubscribe link) plus link domains compared with the sending domain and a postal address for marketing email. With the assistant on, the model suggests a calmer subject, preview text and rewrites of flagged passages. A stored template is shown to the model with its own test data, never with `variables`. The rule-based part is returned also while the assistant is off; `ai.status` says whether the model added its wording (`ok`, `not_requested`, `disabled`, `not_configured`, `rate_limited`, `error`). Prompts include the brand voice and matching facts (workspace notes) unless the privacy settings leave them out.

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `subject` | `string` | Default "". |
| `previewText` | `string` |  |
| `html` | `string` |  |
| `text` | `string` |  |
| `template` | `string` | A stored template (id or slug), rendered with its test data, instead of html and text. |
| `variables` | `object` |  |
| `type` | `"transactional" \| "broadcast"` | `broadcast` (marketing) adds the unsubscribe and postal address checks. Default "broadcast". |
| `fromEmail` | `string` | Sender address: link domains are compared with its domain. |
| `useAi` | `boolean` | Ask the model to word the result. The rule-based part is returned either way, also while the assistant is off. Default true. |
| `connectionId` | `string` | AI connection to use. Defaults to the workspace default. |

### Responses

`200` Success

```
{
  "verdict": "good" | "review" | "risky",
  "findings": [{
    "level": "ok" | "info" | "warning" | "error",
    "code": string,
    "message": string
  }],
  "stats": {
    "words": number,
    "links": number,
    "images": number,
    "subjectLength": number,
    "linkDomains": [string],
    "otherLinkDomains": [string]
  },
  "ai": {
    "status": "ok" | "not_requested" | "disabled" | "not_configured" | "rate_limited" | "error",
    "message": string or null,
    "usage": {
      "connectionId": string,
      "model": string,
      "inputTokens": number or null,
      "outputTokens": number or null,
      "latencyMs": number
    },
    "subject": string or null,
    "previewText": string or null,
    "notes": [string],
    "rewrites": [{
      "original": string,
      "suggestion": string
    }],
    "context": {
      "brandVoice": boolean,
      "facts": [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`)

## Write a campaign from a goal

POST `/v1/ai/write-campaign`

Subject line, preview text and a validated template document (blocks) for a goal and an audience described in words, in the brand voice and with matching facts. Uses template generation (one retry when the first answer is not valid). Nothing is saved. Returns 403 `ai_disabled` while the assistant is turned off and 400 `ai_not_configured` without a connection.

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `goal`required | `string` | What the campaign should achieve, for example "Get trial users to book an onboarding call". |
| `audience` | `string` | Who receives it, in words. Never a list of contacts. |
| `callToAction` | `object` |  |
| `callToAction.label` | `string` |  |
| `callToAction.url` | `string` |  |
| `length` | `"short" \| "medium" \| "long"` | Default "medium". |
| `language` | `string` | Language of the AI wording, for example "German". Default: English for explanations, the content's language for copy. |
| `brand` | `object` |  |
| `brand.primary` | `string` |  |
| `brand.accent` | `string` |  |
| `brand.logoUrl` | `string` |  |
| `brand.companyName` | `string` |  |
| `connectionId` | `string` | AI connection to use. Defaults to the workspace default. |

### Responses

`200` Success

```
{
  "subject": string,
  "previewText": string,
  "document": object,
  "variables": [string],
  "warnings": [string],
  "attempts": number,
  "context": {
    "brandVoice": boolean,
    "facts": [string]
  },
  "usage": {
    "connectionId": string,
    "model": string,
    "inputTokens": number or null,
    "outputTokens": number or null,
    "latencyMs": 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`)

## Translate a template

POST `/v1/ai/translate-template`

Translates every text of a template document (all text blocks, buttons, lists, tables and the footer) and the subject and preheader. Structure, styles, links and {{ variables }} are not sent for translation and stay unchanged; a translated text that changed a variable or a link is kept in the original language (`segments.kept`). Large templates take several model requests. Nothing is saved. Returns 403 `ai_disabled` while the assistant is turned off and 400 `ai_not_configured` without a connection. Prompts include the brand voice and matching facts (workspace notes) unless the privacy settings leave them out.

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `document` | `object` | A template document (`{ version, theme, blocks }`). |
| `template` | `string` | Or a stored template (id or slug): its current version is translated. Nothing is saved. |
| `subject` | `string` |  |
| `preheader` | `string` |  |
| `language`required | `string` | Target language, for example "German" or "pt-BR". |
| `connectionId` | `string` | AI connection to use. Defaults to the workspace default. |

### Responses

`200` Success

```
{
  "document": object,
  "subject": string,
  "preheader": string,
  "language": string,
  "segments": {
    "total": number,
    "translated": number,
    "kept": number
  },
  "warnings": [string],
  "context": {
    "brandVoice": boolean,
    "facts": [string]
  },
  "usage": {
    "connectionId": string,
    "model": string,
    "inputTokens": number or null,
    "outputTokens": number or null,
    "latencyMs": 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`)
