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 and errors are described in the overview.

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.

FieldTypeDescription
enabledboolean
defaultConnectionIdstring or null
writingProfileobject
writingProfile.styleNotesstringHow you write: tone, length, words to avoid. Included in drafting prompts.
writingProfile.signOffstringAdded at the end of drafted replies, for example "Thanks,\nAda".
privacyobject
privacy.brandVoicebooleanInclude the brand voice (style notes and sign-off) in prompts. Default true.
privacy.factsbooleanInclude matching facts (workspace notes) in prompts. Default true.
privacy.providerResponsesbooleanSend provider and SMTP error text (with addresses removed) when explaining a failed email. Off: only codes are sent. Default true.
privacy.recipientDomainsbooleanSend the recipient's domain (for example gmail.com) when explaining a failed email. Default true.
privacy.domainNamesbooleanSend 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.

FieldTypeDescription
namerequiredstring
kindrequired"openai_compatible" | "anthropic" | "google"
modelrequiredstringModel id as the provider names it.
apiKeystringEncrypted at rest and never returned. Optional for local OpenAI-compatible servers such as Ollama.
baseUrlstring (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.
apiVersionstringopenai_compatible: sent as the api-version query parameter (Azure). anthropic: the anthropic-version header (default 2023-06-01).
makeDefaultbooleanUse 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

NameInTypeDescription
idrequiredpathstring

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

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
namestring
modelstring
apiKeystringReplaces the stored key. Send an empty string to remove it.
baseUrlstring (uri) or null
authHeader"bearer" | "api-key"
apiVersionstring or null
makeDefaultboolean

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

NameInTypeDescription
idrequiredpathstring

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

NameInTypeDescription
idrequiredpathstring

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.

FieldTypeDescription
titlerequiredstring
textrequiredstring

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

NameInTypeDescription
idrequiredpathstring

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

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
titlestring
textstring

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

NameInTypeDescription
idrequiredpathstring

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

NameInTypeDescription
daysqueryintegerDefault 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.

FieldTypeDescription
threadIdstringAn inbox thread (received and sent messages).
messageIdstringA received message (inb_ inbox id); its thread is summarized.
emailIdstringA sent email; it is summarized with the replies in its thread.
connectionIdstringAI 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.

FieldTypeDescription
bodystringThe email content (text or HTML).
topicstringWhat the email is about, when there is no body yet.
currentSubjectstring
kind"subject" | "preview" | "both"Default "both".
countintegerDefault 5. 1 to 10.
connectionIdstringAI 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.

FieldTypeDescription
promptrequiredstringFor example "Order shipped notification with tracking button and order summary table".
type"transactional" | "broadcast"Default "transactional".
brandobject
brand.primarystring
brand.accentstring
brand.logoUrlstring
brand.companyNamestring
connectionIdstringAI 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.

FieldTypeDescription
textrequiredstring
moderequired"shorter" | "clearer" | "friendlier" | "more_formal" | "fix_grammar" | "translate" | "custom"
languagestringRequired for translate, for example "German".
instructionstringRequired for custom.
connectionIdstringAI 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.

FieldTypeDescription
emailIdrequiredstringA sent email (msg_ id).
useAibooleanAsk the model to word the result. The rule-based part is returned either way, also while the assistant is off. Default true.
languagestringLanguage of the AI wording, for example "German". Default: English for explanations, the content's language for copy.
connectionIdstringAI 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.

FieldTypeDescription
daysintegerWindow for bounce, complaint and suppression rates. Default 30. 1 to 90.
useAibooleanAsk the model to word the result. The rule-based part is returned either way, also while the assistant is off. Default true.
languagestringLanguage of the AI wording, for example "German". Default: English for explanations, the content's language for copy.
connectionIdstringAI 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.

FieldTypeDescription
subjectstringDefault "".
previewTextstring
htmlstring
textstring
templatestringA stored template (id or slug), rendered with its test data, instead of html and text.
variablesobject
type"transactional" | "broadcast"broadcast (marketing) adds the unsubscribe and postal address checks. Default "broadcast".
fromEmailstringSender address: link domains are compared with its domain.
useAibooleanAsk the model to word the result. The rule-based part is returned either way, also while the assistant is off. Default true.
connectionIdstringAI 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.

FieldTypeDescription
goalrequiredstringWhat the campaign should achieve, for example "Get trial users to book an onboarding call".
audiencestringWho receives it, in words. Never a list of contacts.
callToActionobject
callToAction.labelstring
callToAction.urlstring
length"short" | "medium" | "long"Default "medium".
languagestringLanguage of the AI wording, for example "German". Default: English for explanations, the content's language for copy.
brandobject
brand.primarystring
brand.accentstring
brand.logoUrlstring
brand.companyNamestring
connectionIdstringAI 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.

FieldTypeDescription
documentobjectA template document ({ version, theme, blocks }).
templatestringOr a stored template (id or slug): its current version is translated. Nothing is saved.
subjectstring
preheaderstring
languagerequiredstringTarget language, for example "German" or "pt-BR".
connectionIdstringAI 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)