Docs / Developers and AI

AI assistant

OneSend can help you write, check and troubleshoot email with a model you bring: an OpenAI-compatible endpoint (OpenAI, Azure OpenAI, a gateway, or a local server such as Ollama or LM Studio), Anthropic or Google Gemini.

The assistant only suggests. It never sends email, changes settings or saves templates on its own: you review each result and apply it yourself.

What it does

For the email you send

FeatureWhereWhat you get
Explain this failureLogs: a bounced, failed, deferred, complained or suppressed email (the detail panel and the row menu ⋯)What happened and what to do, in plain words, with links to the page that fixes it (the domain's DNS records, the provider, suppressions, routing)
Deliverability checkDeliverability pageA prioritized list of fixes: SPF, DKIM, DMARC and alignment per domain, bounce and complaint rates overall and per provider, providers out of rotation, missing provider webhooks, suppression growth and where it came from, warm-up and webhook health
Spam checkCampaign editor (review step), template designer (Check)Spammy phrasing, image-to-text ratio, link domains compared with your sending domain, a missing unsubscribe link or postal address in marketing email, all-caps subjects, URL shorteners, and, with AI, a calmer subject, preview text and rewrites of flagged passages
Write a campaign from a goalCampaign editor, content step: Write with AIA subject line, preview text and a template you can edit, from a goal and an audience described in words
Translate a templateTemplate designer: ⋯ → Translate…The whole template (every text, the subject and the preview text) in another language; layout, links and {{ variables }} stay as they are
Generate a templateTemplates, template designer: GenerateA template from a description
Rewrite textTemplate designer, campaign copyShorter, clearer, friendlier, more formal, fixed grammar, translated or as instructed
Subject lines and preview textCampaign editor: SuggestSuggestions from the content or the campaign name

The explanations, the deliverability check and the spam check are rule-based first: known codes (550 5.1.1 user unknown, SPF and DKIM failures, DMARC rejections, full mailboxes, provider limits, rate limits, blocklists) and known problems are recognized without a model, so they work while AI is off. With AI on, the model words the result in plain language (in the dashboard's language) and adds suggestions. Links always come from OneSend, never from the model.

Brand voice and facts

Two things make the results sound like you and get your details right. Both are in Settings → AI:

  • Brand voice: style notes (tone, length, words to use or avoid, how you address people) and a sign-off. Every feature that writes or explains uses it: templates, campaigns, rewrites (except grammar fixes), subject lines, translations, spam-check suggestions, failure explanations and reviews, and reply drafts.
  • Facts the AI can use: short notes such as prices, a refund policy or support hours (up to 200, 8,000 characters each). A fact is included only when its words match what is being written, explained or asked, so unrelated facts are not sent. Each request includes at most 3 facts and 4,000 characters of them (2 and 2,000 to 3,000 for rewrites, checks and explanations).

Admins edit the brand voice; members can add facts.

Set up

AI entry points are visible even before AI is set up. The first time someone uses one:

  • an admin gets a small Connect a model dialog: pick the provider, paste the key, and OneSend tests it, turns AI on and continues with what you were doing;
  • anyone else is asked to have an admin connect a model. Viewers cannot use AI features.

The full form, with several connections, gateways and advanced options, is in Settings → AI → Add connection: pick the provider (the base URL is filled in and the form links to where you create a key), enter the model and the key, and choose Add and test.

Providers

Any service with an OpenAI-compatible POST /chat/completions endpoint works. The list in the dashboard pre-fills these:

ProviderBase URLNotes
OpenAIhttps://api.openai.com/v1
Anthropic(native API)Claude models
Google Gemini(native API)
Hugging Facehttps://router.huggingface.co/v1Use a Hub model ID that supports chat. Add :fastest or :cheapest to let Hugging Face choose the backend. The token needs permission to call Inference Providers
Groqhttps://api.groq.com/openai/v1
Together AIhttps://api.together.xyz/v1
Mistral AIhttps://api.mistral.ai/v1
DeepSeekhttps://api.deepseek.com/v1
xAIhttps://api.x.ai/v1
Fireworks AIhttps://api.fireworks.ai/inference/v1
Ollama (local)http://localhost:11434/v1No key. Needs ONESEND_ALLOW_PRIVATE_NETWORK=true
LM Studio (local)http://localhost:1234/v1No key. Needs ONESEND_ALLOW_PRIVATE_NETWORK=true
Customyour URLAny OpenAI-compatible server or gateway, a Hugging Face Inference Endpoint (its URL followed by /v1), vLLM, or Azure OpenAI (see below)

Model catalogs change often, so the model field takes any ID the provider accepts.

The first connection becomes the default. With several connections, choose Make default on the one features should use. API requests can name another one with connectionId.

API keys are encrypted at rest with ONESEND_SECRET (AES-256-GCM, like sending provider credentials), re-encrypted during key rotation, and never returned by the API: responses show only the last four characters (keyHint). Keys are stripped from error messages and logs.

OpenAI

  • Provider: OpenAI-compatible
  • Base URL: https://api.openai.com/v1
  • Model: a chat model available to your account
  • API key: from your OpenAI account

Azure OpenAI

  • Provider: OpenAI-compatible
  • Base URL: https://<resource>.openai.azure.com/openai/deployments/<deployment> (the deployment-style URL), or https://<resource>.openai.azure.com/openai/v1 for the v1 API
  • Advanced options: key header api-key, API version (for example 2024-10-21) for deployment URLs
  • Model: the deployment or model name

API gateways

  • Provider: Custom
  • Base URL: the gateway's OpenAI-compatible base
  • Model: the gateway's model ID

Local models with Ollama or LM Studio

Local servers run on a private address, which OneSend does not call by default (the same protection that applies to webhooks and self-hosted provider URLs). On a self-hosted server, set:

ONESEND_ALLOW_PRIVATE_NETWORK=true

Then add a connection:

  • Provider: OpenAI-compatible
  • Base URL: http://localhost:11434/v1 (Ollama) or http://localhost:1234/v1 (LM Studio). When OneSend runs in Docker, use the host's address, for example http://host.docker.internal:11434/v1.
  • Model: a model you pulled, for example llama3.2 (ollama pull llama3.2)
  • API key: leave empty

ONESEND_ALLOW_PRIVATE_NETWORK=true also lets webhooks and provider base URLs reach private addresses. Only set it on a server where every workspace member is trusted. Local models are slower; raise ONESEND_AI_TIMEOUT_MS if requests time out. Template generation works best with larger models.

A key is never sent over plain http:// to a public host: use https:// for anything that is not on your own network.

Anthropic

  • Provider: Anthropic
  • Model: for example claude-sonnet-5; see Anthropic's model list
  • API key: from the Claude Console

Requests use the Messages API (POST https://api.anthropic.com/v1/messages, headers x-api-key and anthropic-version: 2023-06-01). Under advanced options you can set another anthropic-version or a gateway URL.

Google Gemini

  • Provider: Google Gemini
  • Model: for example gemini-3.8-flash; see Google's model list
  • API key: from Google AI Studio

Requests use POST https://generativelanguage.googleapis.com/v1beta/models/<model>:generateContent with the key in the x-goog-api-key header (never in the URL).

Privacy

Nothing is sent to a model provider until someone uses a feature. Content goes only to the provider of the connection you chose, under that provider's terms and data retention. For full control, use a local model.

Settings → AI → Privacy decides what may be sent (all on by default):

SettingWhen off
Brand voiceStyle notes and the sign-off are left out of every prompt, including inbox reply drafts
FactsNo facts are sent
Provider error messagesFailure explanations send only codes, not the provider's or receiving server's text
Recipient domainsFailure explanations do not send the recipient's domain (for example gmail.com)
Domain and provider namesYour sending domains and connection names are replaced with placeholders such as domain-1.example and mapped back in the answer

Never sent, whatever the settings:

  • recipient addresses (provider messages have addresses replaced with <address>), recipient lists and contact fields;
  • the subject or content of a failed email;
  • API keys and provider credentials.

The deliverability check sends totals and its findings only. The spam check sends the content being checked with {{ variables }} unfilled: a stored template is shown to the model with its own test data, never with a contact's values. Write a campaign sends your goal and the audience as you described it.

Content is treated as untrusted data: prompts put it inside delimiters and tell the model not to follow instructions in it, the brand voice is applied to tone and wording only, generated templates cannot contain raw HTML blocks, links that are not http(s), mailto:, tel: or a {{ variable }} are replaced, and a translation that changes a variable or a link is discarded for that text.

Prompts and model output are not stored. OneSend stores one usage row per request (feature, model, token counts, duration, error code). To debug, set ONESEND_AI_LOG_PROMPTS=true and LOG_LEVEL=debug; prompts then appear in the server log (keys redacted). Turn it off again afterwards.

Test-mode API keys (os_test_…) cannot add or change AI connections or settings, and cannot use features that read the inbox. They return 403 test_mode.

Costs

Model usage is billed by your model provider, not by OneSend. Settings → AI shows requests and token counts for the last 30 days per feature (GET /v1/ai/usage), when the provider reports them. Each workspace is limited to ONESEND_AI_RATE_LIMIT model requests per minute (default 30); further requests return 429 rate_limited, and the rule-based features then return their result without the model's wording (ai.status: rate_limited). Template generation and Write a campaign can make two requests (one retry when the first answer is not a valid template); translating a large template makes one request per 12,000 characters of text.

API

All endpoints are under /v1/ai. See the interactive reference at /docs for every field.

EndpointPurpose
GET/PATCH /ai/settingsenabled, defaultConnectionId, writingProfile (brand voice), privacy
GET/POST /ai/connections, GET/PATCH/DELETE /ai/connections/:id, POST /ai/connections/:id/testModel connections
GET/POST /ai/notes, GET/PATCH/DELETE /ai/notes/:idFacts the AI can use
GET /ai/usage?days=30Requests and tokens per day, feature and model
POST /ai/explain-failure{ emailId, useAi?, language? } → summary, hints[] (code, title, explanation, actions, links, retryable), facts (SMTP and enhanced codes, provider, recipient domain, the sending domain's SPF/DKIM/DMARC status), ai
POST /ai/deliverability-review{ days?, useAi?, language? } → findings[] (priority, area, title, detail, fix, links, aiText), passed[], stats, skipped[], ai.summary
POST /ai/spam-check{ subject, previewText?, html? | text? | template?, type?, fromEmail?, useAi? } → verdict (good, review, risky), findings[], stats, ai (subject, preview text, rewrites, notes)
POST /ai/write-campaign{ goal, audience?, callToAction?, length?, language?, brand? } → subject, previewText, document, variables, context
POST /ai/translate-template{ document | template, subject?, preheader?, language } → translated document, subject, preheader, segments (total, translated, kept)
POST /ai/generate-template{ prompt, type?, brand? } → a template document that passes validation, subject, preheader, variables, context
POST /ai/rewrite{ text, mode: shorter | clearer | friendlier | more_formal | fix_grammar | translate | custom, language?, instruction? }
POST /ai/subjects{ body?, topic?, kind: subject | preview | both, count } → subjects[], previewTexts[]
POST /ai/summarize{ threadId }, { messageId } or { emailId } → summary[], actionItems[], sources[]

context says what went into a writing prompt: { brandVoice: boolean, facts: string[] } (the titles of the facts used).

Mixed results. explain-failure, deliverability-review and spam-check always return their rule-based part, also while AI is off. ai.status says what the model added: ok, not_requested (useAi: false), disabled, not_configured, rate_limited or error (with ai.message). The other features need AI on.

Settings and connections need an admin; the features need a member (viewers get 403) and a Full access key or a dashboard session. Errors:

StatusCodeMeaning
403ai_disabledThe assistant is turned off for this workspace
400ai_not_configuredNo AI connection
400unsafe_url, insecure_base_urlThe base URL is private (see local models) or plain http with a key
400invalid_document, not_a_block_template, nothing_to_translateTranslate: the document is not a valid designer template, or has no text
403test_modeA test-mode key was used for AI setup or inbox content
429rate_limitedToo many AI requests for this workspace
502ai_provider_errorThe model provider returned an error; details.code is one of auth_failed, permission_denied, rate_limited, quota_exceeded, model_not_found, bad_request, provider_unavailable, blocked, invalid_response, network
504ai_provider_errorThe model provider did not answer in time (details.code timeout)
502ai_invalid_output, ai_invalid_templateThe model's answer could not be used

The SDK exposes the same endpoints as onesend.ai.* (for example onesend.ai.explainFailure({ emailId }), onesend.ai.deliverabilityReview(), onesend.ai.spamCheck({ subject, html }), onesend.ai.writeCampaign({ goal }), onesend.ai.translateTemplate({ template, language })). The SDK retries 5xx responses, which can repeat a model request.

MCP

MCP clients already have their own model, so the MCP server does not wrap the writing features.

Environment variables

VariableDefaultEffect
ONESEND_AI_LOG_PROMPTSfalseLog prompts and model output at debug level
ONESEND_AI_TIMEOUT_MS60000Timeout per model request
ONESEND_AI_RATE_LIMIT30Model requests per minute per workspace
ONESEND_ALLOW_PRIVATE_NETWORKfalseAllow private and local base URLs (local models)

Model responses larger than 2 MB are rejected.