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 byPOST /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.
- GET
/v1/connectionsList connected provider accounts with today's usage - POST
/v1/connectionsConnect a provider account - GET
/v1/connections/{id}Get a connection - PATCH
/v1/connections/{id}Update a connection (rename, pause, limits, credentials) - DELETE
/v1/connections/{id}Disconnect a provider - POST
/v1/connections/{id}/testCheck the credentials still work - GET
/v1/connections/{id}/insightsHealth, affinity, webhooks and sync of a connection - POST
/v1/connections/{id}/health/resetPut a provider back in rotation - POST
/v1/connections/{id}/suppressions/syncImport this provider's suppression list now - POST
/v1/connections/{id}/rotate-webhook-urlRotate the provider webhook URL - POST
/v1/connections/{id}/refresh-quotaRe-detect quota from the provider
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.
- GET
/v1/policiesList routing policies - POST
/v1/policiesCreate a routing policy - GET
/v1/policies/{id}Get a policy - PATCH
/v1/policies/{id}Update a policy (reorder steps, caps, rules, fallback) - DELETE
/v1/policies/{id}Delete a policy - POST
/v1/route/previewDry-run: which provider would send this right now, and why the others would not
Senders & domains
Add a domain once; OneSend registers it on every provider and merges the DNS.
- GET
/v1/domainsList domains with per-provider verification - POST
/v1/domainsAdd a domain once — registered on every provider - GET
/v1/domains/provider-domainsDomains already set up in your providers - GET
/v1/domains/{id}Get a domain and its merged DNS plan - PATCH
/v1/domains/{id}Update a domain: tracking and allowed sending providers - DELETE
/v1/domains/{id}Remove a domain from OneSend - POST
/v1/domains/{id}/verifyRe-check verification on every provider and DNS - POST
/v1/domains/{id}/apply-dnsWrite the DNS plan through the DNS host connection - GET
/v1/domains/{id}/zoneExport the DNS plan as a BIND zone file (text/plain) - GET
/v1/domains/{id}/dns-setupDNS setup instructions for the domain's DNS host - PATCH
/v1/domains/{id}/dns-hostChoose the DNS host or connection for a domain - POST
/v1/domains/{id}/dns-planPreview DNS changes (dry run) - POST
/v1/domains/{id}/dns-applyApply DNS changes - GET
/v1/domains/{id}/diagnosticsDiagnose the DNS records - GET
/v1/receiving-hostsReceiving host catalog - GET
/v1/domains/{id}/receivingReceiving status and records for a domain - PATCH
/v1/domains/{id}/receivingChoose where mail to the domain should arrive - POST
/v1/domains/{id}/receiving/applyWrite the receiving host's MX and SPF records (preview, then confirm)
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.
- GET
/v1/dns-hostsDNS host catalog - GET
/v1/dns-hosts/detectDetect the DNS host of a domain - GET
/v1/dns-hosts/connectionsList DNS host connections - POST
/v1/dns-hosts/connectionsConnect a DNS host - GET
/v1/dns-hosts/connections/{id}Get a DNS host connection - PATCH
/v1/dns-hosts/connections/{id}Update a DNS host connection - DELETE
/v1/dns-hosts/connections/{id}Delete a DNS host connection - POST
/v1/dns-hosts/connections/{id}/testTest a DNS host connection
Templates
Block-based templates with variables, conditional blocks and conditional styling.
- GET
/v1/templatesList templates - POST
/v1/templatesCreate a template - GET
/v1/templates/{id}Get a template (by id or slug) - PATCH
/v1/templates/{id}Update a template - DELETE
/v1/templates/{id}Delete a template - POST
/v1/templates/{id}/renderRender a stored template with variables - POST
/v1/templates/renderRender an ad-hoc template document (no save) - GET
/v1/templates/{id}/versionsList versions of a template
Gallery
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.
- GET
/v1/gallery/statusWhere this server reads the gallery from, and whether this workspace can share templates - GET
/v1/gallery/submissionsThis workspace's gallery submissions - POST
/v1/gallery/submissionsShare a template to the gallery - GET
/v1/galleryBrowse the template gallery - GET
/v1/gallery/{slug}Get a gallery template with its document, sample data and preview - GET
/v1/gallery/{slug}/preview.htmlPreview a gallery template - POST
/v1/gallery/{slug}/useCount a use of a gallery template - POST
/v1/gallery/{slug}/cloneCopy a gallery template into your workspace
Contacts
Contacts and their attributes. Emails are unique per workspace (stored lowercased).
- GET
/v1/contact-attributesList contact attributes - POST
/v1/contact-attributesCreate a contact attribute - DELETE
/v1/contact-attributes/{key}Delete a contact attribute - GET
/v1/contactsList contacts - POST
/v1/contactsCreate or update a contact (by email) - POST
/v1/contacts/bulkBulk actions on contacts - GET
/v1/contacts/exportExport contacts as CSV (streamed) - GET
/v1/contacts/{id}Get a contact - PATCH
/v1/contacts/{id}Update a contact - DELETE
/v1/contacts/{id}Delete a contact - GET
/v1/contacts/{id}/activityContact activity timeline - GET
/v1/contacts/{id}/journeysAutomations a contact went through - GET
/v1/contacts/{id}/exportExport a contact's data (GDPR)
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.
- GET
/v1/contacts/import-presetsCSV import presets - GET
/v1/contacts/importsImport history - POST
/v1/contacts/importsUpload a CSV file (step 1) - GET
/v1/contacts/imports/{id}Get an import (poll while processing) - POST
/v1/contacts/imports/{id}/startMap columns and start the import (step 2) - GET
/v1/contacts/imports/{id}/errors.csvDownload rows that were not imported (CSV)
Campaigns
Marketing campaigns: draft, schedule, send through your providers, and report.
- GET
/v1/campaignsList campaigns with headline stats - POST
/v1/campaignsCreate a draft campaign - GET
/v1/campaigns/{id}Get a campaign - PATCH
/v1/campaigns/{id}Edit a campaign - DELETE
/v1/campaigns/{id}Delete a campaign - GET
/v1/campaigns/{id}/checkCheck a campaign before sending - POST
/v1/campaigns/{id}/duplicateDuplicate as a new draft - POST
/v1/campaigns/{id}/testSend a test email - POST
/v1/campaigns/{id}/scheduleSchedule, or send now - POST
/v1/campaigns/{id}/pausePause sending (emails not yet handed to a provider are held) - POST
/v1/campaigns/{id}/resumeResume a paused campaign - POST
/v1/campaigns/{id}/cancelCancel (emails not yet handed to a provider are dropped) - GET
/v1/campaigns/{id}/ab-testA/B test results - POST
/v1/campaigns/{id}/ab-test/winnerPick the A/B test winner - GET
/v1/campaigns/{id}/reportCampaign report - GET
/v1/campaigns/{id}/recipientsRecipient activity (JSON or CSV) - GET
/v1/campaigns/{id}/safeguardsSafeguards that apply to a campaign
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.
- GET
/v1/automationsList automations - POST
/v1/automationsCreate an automation - GET
/v1/automations/recipesAutomation recipes - GET
/v1/automations/{id}Get an automation - PATCH
/v1/automations/{id}Edit an automation - DELETE
/v1/automations/{id}Delete an automation - POST
/v1/automations/{id}/validateCheck an automation - POST
/v1/automations/{id}/activateActivate (or resume) an automation - POST
/v1/automations/{id}/pausePause an automation - POST
/v1/automations/{id}/stopStop an automation - POST
/v1/automations/{id}/enrollEnroll contacts - POST
/v1/automations/{id}/testTest with one contact - GET
/v1/automations/{id}/reportAutomation report - GET
/v1/automations/{id}/runsList runs - GET
/v1/automations/{id}/runs/{runId}Get a run with its step history - POST
/v1/automations/{id}/runs/{runId}/exitRemove a contact from an automation - GET
/v1/automations/{id}/versionsPublished versions - GET
/v1/automations/{id}/signing-secretWebhook step signing secret - POST
/v1/automations/{id}/rotate-secretRotate the signing secret
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.
- GET
/v1/formsList signup forms - POST
/v1/formsCreate a signup form - POST
/v1/forms/previewPreview a form - GET
/v1/forms/{id}Get a signup form - PATCH
/v1/forms/{id}Update a signup form - DELETE
/v1/forms/{id}Delete a signup form - GET
/v1/forms/{id}/embedEmbed code for a form - GET
/v1/forms/{id}/submissionsList form submissions - POST
/v1/forms/{id}/submissionsSubmit a form from your server
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.
- GET
/v1/deliverabilityDeliverability overview - GET
/v1/deliverability/alertsDeliverability alerts for the dashboard - GET
/v1/deliverability/settingsDeliverability settings - PATCH
/v1/deliverability/settingsChange deliverability settings - GET
/v1/deliverability/guardWorkspace guard - POST
/v1/deliverability/acknowledgeAcknowledge the workspace guard - GET
/v1/deliverability/warmupWarm-up per sending domain - PATCH
/v1/deliverability/warmup/{domain}Change the warm-up of a sending domain - GET
/v1/deliverability/best-timeBest time to send - POST
/v1/deliverability/quality/checkCheck address quality - POST
/v1/deliverability/quality/recheckRe-check the address quality of every contact - POST
/v1/deliverability/inactive/restoreRestore inactive contacts - POST
/v1/deliverability/sunset/runRun sunsetting now
Conversions
Credit purchases, sign-ups and other goals to the email that drove them.
Suppressions
One suppression list shared by every provider.
- GET
/v1/suppressionsList suppressed addresses (shared across every provider) - POST
/v1/suppressionsSuppress an address - GET
/v1/suppressions/statsSuppression counts by reason, origin and provider connection - GET
/v1/suppressions/syncProvider suppression sync status per connection - POST
/v1/suppressions/syncImport provider suppression lists now - DELETE
/v1/suppressions/{email}Remove an address from the suppression list
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.
- GET
/v1/ai/settingsAI settings - PATCH
/v1/ai/settingsUpdate AI settings - GET
/v1/ai/connectionsList AI connections - POST
/v1/ai/connectionsAdd an AI connection - GET
/v1/ai/connections/{id}Get an AI connection - PATCH
/v1/ai/connections/{id}Update an AI connection - DELETE
/v1/ai/connections/{id}Delete an AI connection - POST
/v1/ai/connections/{id}/testTest an AI connection - GET
/v1/ai/notesList workspace notes - POST
/v1/ai/notesAdd a note - GET
/v1/ai/notes/{id}Get a note - PATCH
/v1/ai/notes/{id}Update a note - DELETE
/v1/ai/notes/{id}Delete a note - GET
/v1/ai/usageAI usage - POST
/v1/ai/summarizeSummarize a thread - POST
/v1/ai/subjectsSuggest subject lines and preview text - POST
/v1/ai/generate-templateGenerate a template - POST
/v1/ai/rewriteRewrite text - POST
/v1/ai/explain-failureExplain a failed email - POST
/v1/ai/deliverability-reviewReview deliverability - POST
/v1/ai/spam-checkCheck content for spam before sending - POST
/v1/ai/write-campaignWrite a campaign from a goal - POST
/v1/ai/translate-templateTranslate a template
Workspace
Workspace name and settings, such as tracking defaults and the attribution window.
- GET
/v1/workspaceWorkspace settings (tracking, sandbox, brand) and SMTP details - PATCH
/v1/workspaceUpdate workspace settings - DELETE
/v1/workspaceDelete the workspace - POST
/v1/workspace/exportExport all workspace data - GET
/v1/workspace/exportsList data exports - GET
/v1/workspace/exports/{id}Get a data export - GET
/v1/workspace/exports/{id}/downloadDownload a data export - GET
/v1/workspace/deletionWorkspace deletion status - POST
/v1/workspace/deletion/cancelCancel the workspace deletion
Auth
Dashboard accounts and session tokens.
- POST
/v1/auth/signupCreate an account - POST
/v1/auth/loginSign in - POST
/v1/auth/logoutSign out (revoke the session and clear the cookie) - GET
/v1/auth/meCurrent user, workspace and credentials - POST
/v1/auth/workspaceSwitch the current workspace - POST
/v1/auth/login/2faSign in: second step - POST
/v1/auth/password/forgotRequest a password reset link - POST
/v1/auth/password/checkCheck a password reset link - POST
/v1/auth/password/resetSet a new password with a reset link - GET
/v1/setup/statusFirst-run status
Account
Your own account: profile, password, email address, two-factor authentication and sessions. Session only.
- GET
/v1/accountYour account - PATCH
/v1/accountUpdate your profile - DELETE
/v1/accountDelete your account - POST
/v1/account/passwordChange your password - POST
/v1/account/emailChange your email address - POST
/v1/auth/email/confirmConfirm an email change - POST
/v1/account/email-verificationVerify your email address - GET
/v1/account/sessionsList your active sessions - DELETE
/v1/account/sessions/{id}Revoke a session - POST
/v1/account/sessions/revoke-othersSign out everywhere else - POST
/v1/account/2fa/setupStart two-factor setup - POST
/v1/account/2fa/enableTurn on two-factor authentication - POST
/v1/account/2fa/disableTurn off two-factor authentication - POST
/v1/account/2fa/recovery-codesNew recovery codes - POST
/v1/auth/delete-accountDelete an account without a workspace
Team
Workspace members, roles (owner, admin, member, viewer) and invitations.
- POST
/v1/auth/invitationLook up an invitation - POST
/v1/auth/invitation/acceptAccept an invitation - GET
/v1/team/membersList workspace members - PATCH
/v1/team/members/{userId}Change a member's role - DELETE
/v1/team/members/{userId}Remove a member - POST
/v1/team/leaveLeave the current workspace - POST
/v1/team/transfer-ownershipTransfer ownership to another member - GET
/v1/team/invitationsList invitations - POST
/v1/team/invitationsInvite someone by email - POST
/v1/team/invitations/{id}/resendResend an invitation - DELETE
/v1/team/invitations/{id}Revoke an invitation - GET
/v1/team/settingsTeam security settings - PATCH
/v1/team/settingsRequire two-factor authentication
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.
- GET
/v1/admin/status-incidentsList status page incidents - POST
/v1/admin/status-incidentsPost a status page incident - PATCH
/v1/admin/status-incidents/{id}Update a status page incident - DELETE
/v1/admin/status-incidents/{id}Delete a status page incident - POST
/v1/admin/status-checks/runRun the status self-checks now
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.
- POST
/compat/resend/emailsSend an email (Resend-compatible) - POST
/compat/resend/emails/batchSend up to 100 emails (Resend-compatible) - POST
/compat/sendgrid/v3/mail/sendSend email (SendGrid v3-compatible) - POST
/compat/postmark/emailSend an email (Postmark-compatible) - POST
/compat/postmark/email/withTemplateSend with a template (Postmark-compatible) - POST
/compat/postmark/email/batchSend up to 500 emails (Postmark-compatible) - POST
/compat/postmark/email/batchWithTemplatesSend up to 500 emails with templates (Postmark-compatible)
Public endpoints
Endpoints outside /v1: browser conversions, provider webhooks, inbound ingest and health. Most do not use an API key.