Docs

API reference

Every endpoint of the OneSend API, 288 in all, grouped by area. Generated from the server's OpenAPI document, version 0.1.0.

Base URL https://your-server.example: the address of your OneSend server. Every installation serves the same API at its own address.

OpenAPI 3.1 onesend.email/openapi.json, for client generators and API tools.

The OneSend API sends email through the provider accounts connected to your workspace, such as Resend, Brevo, Amazon SES, Mailgun or SMTP. Messages are routed according to your routing policy and sent through the next provider if one fails or reaches its limit.

Authentication. Authenticate with Authorization: Bearer <token>: an API key (os_live_…, test keys os_test_…) or a session token (oes_…) from POST /auth/login. API key permissions: Full access (full: sending, reading and content), Sending only (send, the default), Read only (read), Admin (admin: Full access plus configuration and API key management) and Conversion tracking (os_pub_…, only POST /t/conversion). Test keys never deliver: they can only send, render templates and read the workspace's sandboxed emails (with the read or full scope) and templates. See the bearer security scheme for details.

Base URL. All endpoints are under /v1. Errors return a JSON body with error.type, error.code and error.message (a sentence you can show to people); validation errors list each field in error.details.

Authentication

Send Authorization: Bearer <token>. The token is an API key or a session token (oes_…) returned by POST /v1/auth/login and POST /v1/auth/signup. The dashboard uses the onesend_session cookie instead; cookie requests that change data must also send X-OneSend-Client: dashboard.

API key permissions (as shown on the dashboard's API keys page):

  • Full access (full): the data plane: sending, reading, and content (templates, contacts, lists, campaigns, automations, forms). Not configuration.
  • Sending only (send, the default for new keys): sending email (including inbox replies and campaign test sends) and recording conversions.
  • Read only (read): read-only endpoints.
  • Admin (admin, created through the API only): Full access plus configuration (sending providers, routing, domains, DNS hosts, webhooks, workspace settings, AI connections, mailboxes, inbound endpoints, license, team) and API key management. Only a signed-in workspace owner or admin can create one.
  • Conversion tracking (os_pub_…): accepted only by POST /t/conversion; safe to put in a web page.

An endpoint that needs a wider permission returns 403 insufficient_scope; configuration changes with a non-admin key name the admin scope. Owner-only actions need the owner, signed in. OAuth access tokens (oat_…) are for /mcp; sent directly they can only read and send (403 oauth_token_not_allowed). Live keys start with os_live_. Test keys (os_test_…) are a sandbox: email sent with them is logged as sandboxed and not delivered, and they can only send, render templates and read the workspace's sandboxed emails (with the read or full scope; every test key of the workspace sees them all) and templates (403 test_key_not_allowed elsewhere).

Endpoints

Emails

Send, inspect and cancel email. Each email shows the providers it was routed through.

Sending providers

Provider accounts connected to this workspace (shown as Sending providers in the dashboard). Credentials are encrypted at rest and never returned.

Provider catalog

Catalog of supported providers and the credentials each one needs.

Routing

Policies decide provider order, caps, rules and what happens when quota runs out.

Senders & domains

Add a domain once; OneSend registers it on every provider and merges the DNS.

DNS hosts

Connect the DNS host of your domains (Cloudflare, Hostinger, GoDaddy, Route 53 and more) with your own API token so OneSend can write records, or get exact instructions for any other host. Tokens are encrypted at rest and never returned.

Templates

Block-based templates with variables, conditional blocks and conditional styling.

The hosted template gallery: browse templates and copy them into your workspace, and share your own for review. Public on the server that hosts it; other servers read it from ONESEND_GALLERY_URL and fall back to the bundled starter templates.

Contacts

Contacts and their attributes. Emails are unique per workspace (stored lowercased).

Lists

Static lists of contacts. A contact can be in many lists.

Segments

Saved conditions over attributes, list membership, engagement and status.

Imports

CSV import: upload, map columns, start, then poll for the result.

Campaigns

Marketing campaigns: draft, schedule, send through your providers, and report.

Automations

Automated journeys: a trigger (list, form, attribute change, custom event, date, campaign engagement, conversion or manual) and steps (emails, waits, branches, attribute and list updates, webhooks, splits), with versions, test runs and reports per step.

Events

Custom events from your app (POST /v1/events/track) that start automations, reach goals and continue waiting runs.

Forms

Hosted signup forms with double opt-in, embed code and submissions.

Archive

Public archive of past campaigns: settings and per-campaign visibility.

Statistics

Delivery and engagement statistics with filters.

Deliverability

Safeguards that protect your provider accounts: automatic campaign pause on high bounce or complaint rates, a workspace guard, warm-up of new sending domains, pacing per mailbox provider, address quality checks, sunsetting of inactive contacts and best time to send.

Conversions

Credit purchases, sign-ups and other goals to the email that drove them.

Suppressions

One suppression list shared by every provider.

Analytics

Deliverability totals by provider, quota usage and the event log.

Webhooks

Outgoing events to your app, Slack or Discord.

API keys

Create and revoke API keys. The full key is returned only once.

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.

Workspace

Workspace name and settings, such as tracking defaults and the attribution window.

Auth

Dashboard accounts and session tokens.

Account

Your own account: profile, password, email address, two-factor authentication and sessions. Session only.

Team

Workspace members, roles (owner, admin, member, viewer) and invitations.

Audit log

Who changed members, roles, API keys, sending providers, domains and settings, and when.

Admin

Instance administration for people listed in ONESEND_ADMIN_EMAILS: status page incidents and self-checks.

Tools

Deliverability tools: DNS checker for any domain, DMARC and SPF builders, header analyzer, address checker and pre-send content check. Results are not stored.

Compatibility

Send endpoints that accept the Resend, SendGrid and Postmark payloads, for moving an app to OneSend without code changes. Outside /v1; authenticate with a OneSend API key the way that provider's SDK passes its key.

Public endpoints

Endpoints outside /v1: browser conversions, provider webhooks, inbound ingest and health. Most do not use an API key.

License

Connected apps

Security