Docs / Developers and AI

REST API

  • Base URL: https://<your host>/v1 (self-hosted default http://localhost:3000/v1)
  • Interactive reference: /docs on your server. OpenAPI 3.1 document: /openapi.json, with an operationId on every operation and a shared ErrorBody error schema.
  • POST /emails and POST /emails/batch accept an Idempotency-Key header; POST /conversions accepts idempotencyKey in the body.
  • Lists: { "data": [...], "nextCursor": "…" | null }; pass nextCursor back as ?cursor= for the next page. A cursor that the server did not issue returns 400 invalid_cursor; pass nextCursor back unchanged.
  • Errors: { "error": { "type", "code", "message", "details"? } } with a matching HTTP status: 400 invalid request, 401 missing or invalid credentials, 402 payment or license required (for example license_required, plan_required, email_limit), 403 permission not allowed, 404 not found, 409 conflict, 413 body too large, 415 body not sent as JSON, 422 the request is valid but cannot be carried out (for example no_provider_for_domain), 429 rate limited, 500 internal error, 503 feature not configured (for example ingest_disabled). See Troubleshooting for common codes.

Authentication

Send Authorization: Bearer <token>. The token is one of:

  • An API key. Live keys start with os_live_, test keys with os_test_. Create them under Developers → API keys.
  • A session token (oes_…), returned as token by POST /v1/auth/login and POST /v1/auth/signup. Use it in scripts that act as a signed-in user, for example to create the first API key.

The dashboard does not use a bearer token. It uses the HttpOnly onesend_session cookie, and every cookie request that changes data must also send X-OneSend-Client: dashboard; without it the server returns 403 csrf_header_required.

API key permissions, with the names the dashboard uses:

Dashboard namescopeAllows
Full accessfullThe data plane: sending, the read endpoints, and content management (templates, contacts, lists, segments, imports, suppressions, campaigns, automations, forms, events). Not configuration. It cannot read API keys, the audit log or pending team invitations (403 session_required): those need a signed-in admin or an Admin key.
Sending onlysendThe data plane, sending only: sending email (including inbox replies and campaign test sends) and POST /conversions. No reads and no content management. The default for new keys.
Read onlyreadThe data plane, reading only: the read (GET) endpoints, except API keys, the audit log and pending team invitations (as for Full access). It cannot send or change anything.
Admin (API only)adminFull access plus the control plane: sending providers (/connections), routing policies, domains and receiving, DNS hosts, webhooks, workspace settings, AI connections and settings, mailboxes, inbound endpoints, connected accounts, inbox rules and automation steps that send data outside the workspace, team and API key management. Created with POST /v1/api-keys and "scope": "admin" by a signed-in workspace owner or admin; only live Admin keys pass. A root credential for the workspace: see below.
Conversion trackingpublishable (os_pub_…)Only POST /t/conversion. Safe to put in a web page.

POST /v1/api-keys creates a Sending only key unless you pass scope. A key that creates keys (a live Admin key) can only create keys no wider than itself: the same or a narrower scope, and within its own domainIds, mailboxIds, limits, recipientAllowlist, expiresAt, allowedIps and grants (403 key_wider_than_creator).

Restrictions a key can carry, enforced in every edition:

  • domainIds: sender domains it may send from (403 domain_not_allowed).
  • recipientAllowlist: domains (with subdomains; *.example.com for subdomains only) and addresses it may send to (403 recipient_not_allowed).
  • limits.perHour, limits.perDay: messages per clock hour and UTC day, shared by every server process (429 key_rate_limited with Retry-After).
  • expiresAt: after it, 401 key_expired.
  • allowedIps: IPv4 and IPv6 addresses and CIDR ranges it may be used from (403 ip_not_allowed). The address is the client address the server sees: set ONESEND_TRUST_PROXY behind a proxy.
  • grants: extra read permissions on top of the scope, so a narrow key can do one more thing without becoming a Full access key. templates:read allows GET /v1/templates and GET /v1/templates/{id}; gallery:submit allows GET /v1/gallery/status, GET /v1/gallery/submissions and POST /v1/gallery/submissions. The Mac app's link key is a Sending only key with both grants. Nothing else is opened by a grant.

An Admin key is a root credential for the workspace. It can change configuration, invite people, change members' roles and manage API keys. When it is revoked or reported as leaked, the keys it created or rotated are revoked, its invitations canceled (and the people who joined through them removed), and the inbox rules, mailbox forwarding and automation webhook steps it set up turned off. By design, some of what it did stays, because it is ordinary workspace configuration: webhook endpoints, sending connections and domains it added, campaigns it scheduled, role changes it made to existing members, and other configuration it changed. Use Sending only or Full access keys for applications; create an Admin key only when an application needs to change configuration, with expiresAt and allowedIps; after revoking one, review the audit log (GET /v1/audit-log) for what it changed.

PATCH /v1/api-keys/{id} changes the name, expiresAt and allowedIps; a key making an expired key live again is held to the limit of keys its creator made (400 too_many_keys). POST /v1/api-keys/{id}/rotate returns a new secret for the same key; the old secret keeps working for gracePeriodSeconds (default 24 hours, at most 7 days). An API key can rotate only itself and the keys in its own creator chain (403 not_in_key_chain); the key that made a rotation is recorded, so revoking it also revokes the key it rotated, and a leak report of the old secret of a key last rotated with an API key revokes the whole key (a rotation by a signed-in person stops only the old secret). Keys list lastUsedAt, lastUsedIp and lastUsedUserAgent. New keys end in a 6-character checksum so leaked keys can be recognized offline; older keys keep working. See SECURITY.md.

Keys list who created them: createdByUserId (the member, directly or through a key they created) and createdByKeyId (the key, when a key created it). Revoking a key, or a leak report about it, also revokes the keys it created or rotated, and the keys those created or rotated, until none is left (in bulk, with a final sweep for a key created meanwhile; a request that creates a key with a key being revoked gets 401 key_revoked and the new key is revoked); each is recorded in the audit log and the owners get one alert with their number. A very large chain finishes in background jobs: the alert then says the rest continues in the background, and a second alert gives the total. It also cancels the invitations the key sent and removes the members who joined through them (POST /v1/team/invitations with a key ties the invitation to the key), and in turn the invitations those members sent and the members who joined through them (prior members and the owner are kept); it turns off the inbox rules, mailbox forwarding and automation webhook steps the keys set up, and does so once more a couple of minutes after the chain is done. A key can have at most 100 keys it created that are not revoked, expired ones included (ONESEND_MAX_KEYS_PER_KEY; over it: 400 too_many_keys); keys created in the dashboard are not limited. Removing a member from the workspace (or their leaving it, or deleting their account) revokes the keys they created at once, with one alert to the owners for the member; the keys those keys created, the audit entries and turning off what the keys set up follow in background jobs within moments. Limitation: keys created before key creators were recorded (before migration 0034) by another key have neither field, so removing the member behind them does not revoke them, and what they set up keeps running. Keys created by a key since migration 0035 record that key, so revoking it still reaches them. Owners should review admin keys created before 0034 (createdByUserId and createdByKeyId both null) and rotate or revoke the ones nobody can account for.

Any key can be limited further: domainIds (only those sender domains), mailboxIds (only those mailboxes; 403 mailbox_scope elsewhere), recipientAllowlist and limits (sends per hour and per day). See Agent inbox.

Configuration changes (control-plane writes) need a signed-in admin or owner, or a live Admin key. A Full access, Sending only or Read only key gets 403 insufficient_scope there, with a message that names the admin scope. Owner-only actions (deleting the workspace or canceling its deletion, transferring ownership) need the owner, signed in; API keys get 403 session_required. An endpoint that needs a wider permission returns 403 insufficient_scope.

Some changes are control plane by what they do, wherever they live:

  • connected accounts (/v1/accounts, which hold mailbox passwords): API keys need the Admin scope (signed-in members still manage the accounts they connected), and changing an account's IMAP or SMTP host, port or secure needs its password (and SMTP password) again in the same request (400 credentials_required);
  • an inbox rule that forwards to an address outside the workspace (any address not on a domain whose ownership the workspace verified, connected account addresses included), calls a webhook, or delivers into a mailbox that does either, and an automation webhook step: a signed-in admin or an Admin key. The owners get a security alert, an outside forward address receives mail only after it confirmed by email (the link works for 14 days; saving again sends a new one), and such a rule stops when the key that made it is revoked or reported as leaked, or when the member who made it leaves the workspace (their connected mailboxes are paused too). Turning it back on (enabled: true) needs an admin and alerts the owners again. Mail a deliver rule routes into a mailbox is forwarded outside or sent to that mailbox's webhook only when an admin created or last changed the rule (approvedForOutward, with approvedAt; the upgrade that added it, migration 0035, approved the rules that already did this then, except rules into a mailbox whose forwarding OneSend had turned off, and migration 0037 takes that approval back from such rules that 0035 approved and no admin approved since). An automation's webhook steps stop (webhookDisabledReason; the steps are skipped, the rest runs) when the key that created the automation or added the step is revoked or reported as leaked, until an admin saves the steps again. Connecting a mailbox with an API key also alerts the owners;
  • a mailbox's forwardTo addresses outside the workspace and its webhookUrl: a signed-in admin or an Admin key, with the same alert and confirmation by email. They are turned off when the key that set them is revoked or reported as leaked, or the member who set them leaves the workspace, and stay off, also when the mailbox is saved again, until an admin calls POST /v1/inbox/mailboxes/{id}/forwarding/enable;
  • removing a member from the workspace (or their leaving it) revokes the API keys they created and turns off the inbox rules and mailbox forwarding and webhooks they set up that send mail out of the workspace;
  • turning Sandbox mode on or off, and pausing a sending provider: a signed-in admin only (API keys: 403 session_required), because they stop all delivery, the owners' security alerts included. While Sandbox mode is on, GET /v1/workspace has sandboxPending (scheduledCampaigns, activeAutomationRuns): what sends for real once it is off; the PATCH that turns it off answers with the same counts, and the dashboard asks with them before turning it off;
  • the server's license (/v1/license): its instance admins, or the owner of its first workspace, signed in (never an API key). See License key.

API keys cannot cancel system email (security alerts, sign-in and invitation links: 403 system_email), and an invitation's link is returned only to a signed-in admin. An invitation sent with an API key is canceled, and the member who joined through it removed (with the invitations that member sent, and the members who joined through those), when that key (or a key that created it) is revoked or reported as leaked; an admin sending it again from the dashboard unties it from the key. An invitation cannot be accepted once the person who sent it is no longer a member or the key it was sent with is revoked (400 invitation_revoked).

OAuth access tokens (oat_…) issued to MCP apps act for the person who connected the app, never above that person's role, when they are used through the MCP endpoint (/mcp). Sent directly to the REST API, they can only read and send email (POST /emails, POST /emails/batch, inbox replies and new messages); anything else returns 403 oauth_token_not_allowed.

Session tokens also carry the person's workspace role (owner, admin, member, viewer). A role that is too low returns 403 insufficient_role; a workspace that requires two-factor authentication returns 403 two_factor_required to sessions that did not sign in with it, also on the provider-compatible endpoints (/compat/…) and SMTP, which apply the same rules as POST /emails. Accounts with two-factor authentication get 401 mfa_required from POST /auth/login, with error.details.mfaToken to send to POST /auth/login/2fa. See Team and account security.

Test keys (os_test_…) are a sandbox. They can only:

  • send: POST /emails, POST /emails/batch, the provider-compatible endpoints under /compat and new inbox messages (POST /inbox/compose). The email is logged with status sandboxed and never reaches a provider;
  • render and preview content: POST /templates/render, POST /templates/{id}/render, POST /forms/preview;
  • read sandboxed emails: GET /emails and GET /emails/{id} only return emails with status sandboxed (a live email is 404). These are all of the workspace's sandboxed emails, whichever test key sent them (or the dashboard in Sandbox mode): give each environment its own workspace when one must not read another's test email. Reading needs a test key with the read or full scope; a test key has the default scope send, which only sends (403 insufficient_scope on reads);
  • read what sending needs: GET /templates, GET /templates/{id}, GET /providers and GET /auth/me.

Everything else returns 403 test_key_not_allowed, including canceling or resending email, the license, settings and the inbox. The check applies to the decoded path, so percent-encoded paths are treated the same way.

Endpoints

Paths are relative to /v1.

AreaEndpoints
Auth and workspacePOST /auth/signup · POST /auth/login · POST /auth/logout · GET /auth/me (with capabilities: edition, inbox, connectedAccounts, encryptMail, cloudLink) · GET /setup/status (no authentication: whether an account exists yet, the database kind until then, and the sign-up mode; never paths, hosts or secrets) · GET/PATCH /workspace
TeamGET /team/members · PATCH/DELETE /team/members/:userId · POST /team/leave · POST /team/transfer-ownership · GET/POST /team/invitations · POST /team/invitations/:id/resend · DELETE /team/invitations/:id · GET/PATCH /team/settings · invitee side: POST /auth/invitation · POST /auth/invitation/accept. See Team and account security
Account (sessions only)GET/PATCH /account · POST /account/password · POST /account/email · POST /auth/email/confirm · GET /account/sessions · DELETE /account/sessions/:id · POST /account/sessions/revoke-others · POST /account/2fa/{setup,enable,disable,recovery-codes} · POST /auth/login/2fa · POST /auth/workspace (switch workspace) · POST /auth/password/{forgot,check,reset}
Audit logGET /audit-log (filters: action or prefix such as member., actor, target, since, until) · GET /audit-log/export (CSV)
EmailsPOST /emails · POST /emails/batch · GET /emails · GET /emails/:id · POST /emails/:id/cancel · POST /emails/:id/resend
Provider catalogGET /providers
Sending providers (connections)GET/POST /connections · GET/PATCH/DELETE /connections/:id · POST /connections/:id/test · POST /connections/:id/refresh-quota · POST /connections/:id/rotate-webhook-url
RoutingGET/POST /policies · GET/PATCH/DELETE /policies/:id (steps take stream: transactional or broadcast; rules match fromDomain) · POST /route/preview (candidates say preferred, lastResort and code; domain is the From domain's rule, error is set when no provider can send for it). Affinity, spillover cap and provider health thresholds are workspace settings (routing, providerHealth in PATCH /deliverability/settings)
Provider reputationGET /connections/:id/insights (health against the thresholds, affinity share, webhooks, status checks, sync state) · POST /connections/:id/health/reset · POST /connections/:id/suppressions/sync. Connections include webhookSeenAt and reputation
Senders & domainsGET/POST /domains · GET/PATCH/DELETE /domains/:id (PATCH: tracking and allowedConnections, see Tracking per domain and Which providers send for a domain) · POST /domains/:id/verify · POST /domains/:id/apply-dns · GET /domains/:id/zone · GET /domains/:id/dns-setup · PATCH /domains/:id/dns-host · POST /domains/:id/dns-plan · POST /domains/:id/dns-apply · GET /domains/:id/diagnostics · GET/PATCH /domains/:id/receiving · POST /domains/:id/receiving/apply (preview, then confirm) · GET /receiving-hosts. See Using any DNS host and Receiving email
DNS hostsGET /dns-hosts · GET /dns-hosts/detect?domain= · GET/POST /dns-hosts/connections · GET/PATCH/DELETE /dns-hosts/connections/:id · POST /dns-hosts/connections/:id/test. Tokens are encrypted at rest and never returned
TemplatesGET/POST /templates · GET/PATCH/DELETE /templates/:id · POST /templates/:id/render · POST /templates/render · GET /templates/:id/versions
GalleryGET /gallery · GET /gallery/:slug · GET /gallery/:slug/preview.html · POST /gallery/:slug/clone · GET /gallery/status · GET/POST /gallery/submissions (see Templates)
InboxGET/POST /inbox/mailboxes · POST /inbox/mailboxes/bulk · GET/PATCH/DELETE /inbox/mailboxes/:id · GET /inbox/mailboxes/:id/messages · POST /inbox/mailboxes/:id/rotate-secret (mailboxes take domains to receive on several domains, and access: workspace, members or personal) · GET /inbox/folders/:folder/count · POST /inbox/folders/:folder/empty (Trash and Spam) · GET /inbox/messages (search) · GET/PATCH /inbox/messages/:id · POST /inbox/messages/:id/reply · POST /inbox/compose · GET/PATCH /inbox/threads/:threadId · GET/POST /inbox/threads/:threadId/notes · DELETE /inbox/notes/:id · GET /inbox/sent · GET /inbox/sent/:id · GET/POST /inbox/drafts · GET/PATCH/DELETE /inbox/drafts/:id · POST /inbox/drafts/:id/send · GET/POST /inbox/labels · PATCH/DELETE /inbox/labels/:id · GET /inbox/members · GET/POST /inbox/rules · GET/PATCH/DELETE /inbox/rules/:id · POST /inbox/rules/{reorder,test} · POST /inbox/rules/:id/rotate-secret. See Inbox. With ONESEND_INBOX=off (the default on the cloud edition) every inbox, agent inbox, provider inbound and connected account endpoint answers 403 inbox_unavailable, and list endpoints answer { "data": [], "available": false }
Agent inboxPOST /agent/mailboxes · GET /agent/me · POST /agent/extract · GET /inbox/stream (Server-Sent Events) · GET /inbox/messages/wait · GET /inbox/messages/:id?view=agent · GET /inbox/threads/:threadId?view=agent · GET/PATCH /inbox/mailboxes/:id/agent · GET /inbox/approvals · POST /inbox/approvals/:id/{approve,reject} · GET /oauth/grants · DELETE /oauth/grants/:id. See Agent inbox
Connected accounts (unified inbox)GET /accounts/providers · GET/POST /accounts · POST /accounts/test · GET/PATCH/DELETE /accounts/:id · GET/PATCH /accounts/:id/folders · POST /accounts/:id/sync · OAuth: GET /accounts/oauth/providers · POST /accounts/oauth/:provider/start. Inbox: `?account=acc_…ownall&accountFolder=… on GET /inbox/messages, accountId on POST /inbox/compose`. See Unified inbox
Provider inboundGET /inbound-endpoints/providers · GET/POST /inbound-endpoints · PATCH/DELETE /inbound-endpoints/:id (admin). See Unified inbox
Calendar/calendar/calendars, /calendar/events, invitations and answers, reminders, ICS import and export, the private feed, free/busy. See Calendar
Booking pages/booking/profile, /booking/event-types, /booking/bookings; public pages at /book/:handle (outside /v1). See Booking pages
Drive/drive/drives, folders and files, chunked uploads (/drive/uploads), versions, Trash, shares and public links (/share/:token outside /v1), usage. See Drive
Mail importPOST /inbox/imports · chunked uploads · GET /inbox/imports[/:id] · POST /inbox/imports/preview. See Importing mail
LicenseGET /license · POST /license · POST /license/refresh · DELETE /license · POST /license/free-other. Without an active key on a server that needs one, live sends and the workspace endpoints above answer 402 license_required. See License key
ContactsGET/POST /contacts · GET/PATCH/DELETE /contacts/:id · GET /contacts/:id/activity · POST /contacts/bulk · GET /contacts/export · GET/POST /contact-attributes · DELETE /contact-attributes/:key
Lists & segmentsGET/POST /lists · GET/PATCH/DELETE /lists/:id · GET/POST /segments · GET/PATCH/DELETE /segments/:id · POST /segments/preview
Imports (CSV)POST /contacts/imports (upload) · POST /contacts/imports/:id/start (map + consent) · GET /contacts/imports[/:id] · GET /contacts/imports/:id/errors.csv · GET /contacts/import-presets
Signup formsGET/POST /forms · GET/PATCH/DELETE /forms/:id · GET /forms/:id/embed · GET/POST /forms/:id/submissions · POST /forms/preview. See Signup forms and archive
Public archiveGET/PATCH /archive/settings · GET/PUT /campaigns/:id/archive
CampaignsGET/POST /campaigns · GET/PATCH/DELETE /campaigns/:id · POST /campaigns/:id/{test,schedule,pause,resume,cancel,duplicate} · GET /campaigns/:id/check · GET /campaigns/:id/report · GET /campaigns/:id/recipients · GET /campaigns/:id/ab-test · POST /campaigns/:id/ab-test/winner. See A/B testing
AutomationsGET/POST /automations · GET /automations/recipes · GET/PATCH/DELETE /automations/:id · POST /automations/:id/{activate,pause,stop,validate,enroll,test,rotate-secret} · GET /automations/:id/{report,runs,versions,signing-secret} · GET /automations/:id/runs/:runId · POST /automations/:id/runs/:runId/exit · GET /contacts/:id/journeys. See Automations
Custom eventsPOST /events/track (Sending only keys allowed) · GET /events/tracked
StatisticsGET /statistics/overview (filters: type, campaign, provider, sending domain, recipient domain, tag, template; compares with the previous period)
ConversionsPOST /conversions · GET /conversions · browser: POST /t/conversion with a Conversion tracking key (os_pub_…) and the /t/onesend.js script
SuppressionsGET/POST /suppressions (filters: q, reason, origin, connectionId, provider, scope, temporary, expired; each entry has origin, provider, connectionId, detail, expiresAt and allProviders: true) · DELETE /suppressions/:email · GET /suppressions/stats · GET /suppressions/sync · POST /suppressions/sync (connectionId optional; 202). One list for every provider: see Deliverability
AnalyticsGET /analytics/summary · GET /analytics/quota (pooled.excluded lists Sandbox, paused and failing connections left out of the pooled totals) · GET /events
DeliverabilityGET /deliverability · GET /deliverability/alerts · GET/PATCH /deliverability/settings · GET /deliverability/guard · POST /deliverability/acknowledge (owner or admin session) · GET /deliverability/warmup · PATCH /deliverability/warmup/:domain · GET /deliverability/best-time · POST /deliverability/quality/{check,recheck} · POST /deliverability/inactive/restore · POST /deliverability/sunset/run · GET /campaigns/:id/safeguards. See Deliverability safeguards
Deliverability toolsPOST /tools/dns · POST /tools/dmarc · POST /tools/spf · POST /tools/headers · POST /tools/address · POST /tools/content. Any key permission; rate-limited per workspace; nothing stored. See Deliverability tools
Keys & webhooksGET/POST /api-keys · PATCH/DELETE /api-keys/:id · POST /api-keys/:id/rotate · GET/POST /webhooks · DELETE /webhooks/:id · POST /webhooks/:id/test · POST /webhooks/:id/rotate-secret
Data export and deletionPOST /workspace/export · GET /workspace/exports[/:id] · GET /workspace/exports/:id/download (signed token or an owner/admin session) · DELETE /workspace (owner; 7-day grace period) · GET /workspace/deletion · POST /workspace/deletion/cancel · GET /contacts/:id/export · DELETE /contacts/:id?erase=true · DELETE /account · POST /auth/delete-account. See Privacy
Status page adminGET/POST /admin/status-incidents · PATCH/DELETE /admin/status-incidents/:id · POST /admin/status-checks/run. Instance admins (ONESEND_ADMIN_EMAILS) with a session only. Public: GET /status, GET /status.json (outside /v1, with ONESEND_STATUS_PAGE=on). See Status page
AI assistantGET/PATCH /ai/settings · GET/POST /ai/connections · GET/PATCH/DELETE /ai/connections/:id · POST /ai/connections/:id/test · POST /ai/{summarize,draft-reply,subjects,generate-template,rewrite,triage,ask} · GET/POST /ai/notes · GET/PATCH/DELETE /ai/notes/:id · GET /ai/usage. Off until turned on; see AI assistant

Outside /v1

  • Provider-compatible sends for migration (tag Compatibility in /docs): POST /compat/resend/emails and /compat/resend/emails/batch (Authorization: Bearer <OneSend key>), POST /compat/sendgrid/v3/mail/send (Bearer), POST /compat/postmark/email, /email/batch, /email/withTemplate and /email/batchWithTemplates (X-Postmark-Server-Token: <OneSend key>). They accept each provider's payload, go through the normal send path and answer in that provider's response and error shapes. See Migration guides.
  • Provider webhooks: POST /hooks/:provider/:connectionId/:token. Use the webhookUrl returned by GET /v1/connections/:id; the last segment is a secret token signed with ONESEND_SECRET. OneSend registers this URL itself with providers that support it. POST /v1/connections/:id/rotate-webhook-url issues a new token; the old URL stops working at once.
  • Inbound ingest from the Cloudflare Worker: POST /ingest/cloudflare.
  • Provider inbound: POST /ingest/:provider/:id/:token (Mailgun: …/mime), the URL returned once by POST /v1/inbound-endpoints. Connected account push notifications: POST /hooks/accounts/:provider. OAuth sign-in return: GET /accounts/oauth/callback/:provider.
  • Conversions from a web page: POST /t/conversion with a Conversion tracking key, and the /t/onesend.js script.
  • Health: GET /healthz (503 when the database is unreachable).
  • Remote MCP: /mcp (Streamable HTTP) and OAuth 2.1 for it: /.well-known/oauth-protected-resource[/mcp], /.well-known/oauth-authorization-server, POST /oauth/register, GET /oauth/authorize, POST /oauth/token, POST /oauth/revoke. See MCP.
  • Signup forms: hosted page GET /f/:formId, POST /f/:formId/submit (form post or JSON), /f/:formId/embed.js, and the double opt-in page GET/POST /f/confirm/:token.
  • Public archive: /a/:workspace, /a/:workspace/:slug (.md for Markdown), /a/:workspace/feed.xml, /sitemap.xml and /robots.txt. Only archive pages and /docs are indexable; every other response has X-Robots-Tag: noindex.
  • Links inside sent email: open tracking /t/o/:token, click tracking /t/c/:token, one-click unsubscribe /u/:token (RFC 8058) and view in browser /v/:token.

The webhook, ingest, conversion and health endpoints are in the OpenAPI document under Public endpoints. The link endpoints are not, because only links generated by the server use them.

Send an email

POST /v1/emails
Authorization: Bearer os_live_…
Idempotency-Key: receipt-1042
Content-Type: application/json

{
  "from": "Acme <billing@acme.dev>",
  "to": ["ada@example.com"],
  "template": "receipt",
  "variables": { "order": { "id": 1042, "total": 49 }, "status": "paid" },
  "tags": ["billing"],
  "type": "transactional"
}
{ "id": "msg_01JC…", "status": "queued" }

Send the template's id or slug in template and its values in variables; do not render the HTML yourself. OneSend renders the published version of the template (subject, preheader and HTML) and gives the provider finished HTML. The same request works with every provider and keeps working when the email fails over to another provider, and editing the template in the dashboard changes what is sent without a code change. subject is optional with a template; when you send one, it overrides the template subject and is filled in with the same variables.

The receipt template must exist in your workspace; clone one from the gallery with POST /gallery/receipt-verdant/clone and { "slug": "receipt" }. GET /templates lists the slugs in your workspace.

For a one-off email without a template, send the content instead:

POST /v1/emails
Authorization: Bearer os_live_…
Content-Type: application/json

{ "from": "Acme <billing@acme.dev>", "to": "ada@example.com", "subject": "Your sign-in code", "html": "<p>Your code is <b>482913</b></p>", "text": "Your code is 482913" }

html, text or template is required. {{variables}} in a raw subject and html are filled in from variables too.

When a template uses a variable that the request does not provide, the response also has warnings, for example ["Missing variable: name"]; the email is still queued with that variable empty. Each of to, cc and bcc takes at most 50 addresses, and at most 100 across the three. Validation errors return 400 validation_failed with a readable error.message and one entry per field in error.details (path, field, message, code).

POST /emails/:id/resend sends the same content again. It returns 409 body_unavailable when the body was deleted by data retention. Optional fields: policy (choose a routing policy), provider (force one connection, which disables failover), scheduledAt, tracking: { opens, clicks } (wins over the From domain's and the workspace's tracking settings), attachments, headers and metadata.

When the From domain is a domain of the workspace and no provider of the routing path may or can send for it, the request returns 422 no_provider_for_domain with the domain in error.domain. See Which providers send for a domain.

Outgoing webhooks

Register an endpoint to receive normalized events such as email.delivered, email.bounced and email.received. HTTP deliveries are signed with HMAC-SHA256 (X-OneSend-Signature: v1=<hex> over timestamp + "." + body); Slack and Discord endpoints get formatted messages. See Webhooks for the event list, payload, signature verification and retries.

Marketing

Contacts, lists, segments, CSV import, campaigns, reports and conversion tracking are described in Marketing.

Campaign rates: delivery = delivered/sent · open = unique opens/delivered · click = unique clicks/delivered · click-to-open = unique clicks/unique opens · bounce = (hard + soft)/sent · unsubscribe, complaint and conversion = count/delivered. "Delivered" means accepted by the provider and not bounced.