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
| Feature | Where | What you get |
|---|---|---|
| Explain this failure | Logs: 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 check | Deliverability page | A 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 check | Campaign 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 goal | Campaign editor, content step: Write with AI | A subject line, preview text and a template you can edit, from a goal and an audience described in words |
| Translate a template | Template 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 template | Templates, template designer: Generate | A template from a description |
| Rewrite text | Template designer, campaign copy | Shorter, clearer, friendlier, more formal, fixed grammar, translated or as instructed |
| Subject lines and preview text | Campaign editor: Suggest | Suggestions 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:
| Provider | Base URL | Notes |
|---|---|---|
| OpenAI | https://api.openai.com/v1 | |
| Anthropic | (native API) | Claude models |
| Google Gemini | (native API) | |
| Hugging Face | https://router.huggingface.co/v1 | Use 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 |
| Groq | https://api.groq.com/openai/v1 | |
| Together AI | https://api.together.xyz/v1 | |
| Mistral AI | https://api.mistral.ai/v1 | |
| DeepSeek | https://api.deepseek.com/v1 | |
| xAI | https://api.x.ai/v1 | |
| Fireworks AI | https://api.fireworks.ai/inference/v1 | |
| Ollama (local) | http://localhost:11434/v1 | No key. Needs ONESEND_ALLOW_PRIVATE_NETWORK=true |
| LM Studio (local) | http://localhost:1234/v1 | No key. Needs ONESEND_ALLOW_PRIVATE_NETWORK=true |
| Custom | your URL | Any 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), orhttps://<resource>.openai.azure.com/openai/v1for the v1 API - Advanced options: key header
api-key, API version (for example2024-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) orhttp://localhost:1234/v1(LM Studio). When OneSend runs in Docker, use the host's address, for examplehttp://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):
| Setting | When off |
|---|---|
| Brand voice | Style notes and the sign-off are left out of every prompt, including inbox reply drafts |
| Facts | No facts are sent |
| Provider error messages | Failure explanations send only codes, not the provider's or receiving server's text |
| Recipient domains | Failure explanations do not send the recipient's domain (for example gmail.com) |
| Domain and provider names | Your 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.
| Endpoint | Purpose |
|---|---|
GET/PATCH /ai/settings | enabled, defaultConnectionId, writingProfile (brand voice), privacy |
GET/POST /ai/connections, GET/PATCH/DELETE /ai/connections/:id, POST /ai/connections/:id/test | Model connections |
GET/POST /ai/notes, GET/PATCH/DELETE /ai/notes/:id | Facts the AI can use |
GET /ai/usage?days=30 | Requests 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:
| Status | Code | Meaning |
|---|---|---|
| 403 | ai_disabled | The assistant is turned off for this workspace |
| 400 | ai_not_configured | No AI connection |
| 400 | unsafe_url, insecure_base_url | The base URL is private (see local models) or plain http with a key |
| 400 | invalid_document, not_a_block_template, nothing_to_translate | Translate: the document is not a valid designer template, or has no text |
| 403 | test_mode | A test-mode key was used for AI setup or inbox content |
| 429 | rate_limited | Too many AI requests for this workspace |
| 502 | ai_provider_error | The 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 |
| 504 | ai_provider_error | The model provider did not answer in time (details.code timeout) |
| 502 | ai_invalid_output, ai_invalid_template | The 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
| Variable | Default | Effect |
|---|---|---|
ONESEND_AI_LOG_PROMPTS | false | Log prompts and model output at debug level |
ONESEND_AI_TIMEOUT_MS | 60000 | Timeout per model request |
ONESEND_AI_RATE_LIMIT | 30 | Model requests per minute per workspace |
ONESEND_ALLOW_PRIVATE_NETWORK | false | Allow private and local base URLs (local models) |
Model responses larger than 2 MB are rejected.