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.
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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| Field | Type | Description |
|---|---|---|
namerequired | string | |
kindrequired | "openai_compatible" | "anthropic" | "google" | |
modelrequired | 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Request body
| 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Responses
Errors: 400, 401, 403, 404, 409, 429, 500
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Responses
{
"ok": boolean,
"model": string,
"latencyMs": number,
"sample": string or null,
"error": {
"code": string,
"message": string
}
}Errors: 400, 401, 403, 404, 409, 429, 500
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
{
"data": [{
"id": string,
"object": "ai_note",
"title": string,
"text": string,
"createdAt": string,
"updatedAt": string
}]
}Errors: 400, 401, 403, 404, 429, 500
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Add a note
POST /v1/ai/notes
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
titlerequired | string | |
textrequired | string |
Responses
{
"id": string,
"object": "ai_note",
"title": string,
"text": string,
"createdAt": string,
"updatedAt": string
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Responses
{
"id": string,
"object": "ai_note",
"title": string,
"text": string,
"createdAt": string,
"updatedAt": string
}Errors: 400, 401, 403, 404, 429, 500
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
title | string | |
text | string |
Responses
{
"id": string,
"object": "ai_note",
"title": string,
"text": string,
"createdAt": string,
"updatedAt": string
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Responses
Errors: 400, 401, 403, 404, 409, 429, 500
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| Field | Type | Description |
|---|---|---|
promptrequired | 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| Field | Type | Description |
|---|---|---|
textrequired | string | |
moderequired | "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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| Field | Type | Description |
|---|---|---|
emailIdrequired | 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| Field | Type | Description |
|---|---|---|
goalrequired | 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| 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 | |
languagerequired | string | Target language, for example "German" or "pt-BR". |
connectionId | string | AI connection to use. Defaults to the workspace default. |
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)