---
title: "REST API"
description: "The OneSend REST API: base URL, authentication with API keys, endpoints, sending an email, idempotency keys, pagination and errors. The full reference is generated from the live API."
url: https://onesend.email/docs/api/
---
# 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](https://onesend.email/docs/troubleshooting/) for common codes.

<a id="authentication"></a>
## 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 name | `scope` | Allows |
|---|---|---|
| Full access | `full` | The 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 only | `send` | The 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 only | `read` | The 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) | `admin` | Full 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 tracking | `publishable` (`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](https://onesend.email/security/policy/#leaked-api-keys).

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](https://onesend.email/docs/agent-inbox/#scoped-keys).

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](https://onesend.email/docs/self-hosting/#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](https://onesend.email/docs/team/).

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`.

| Area | Endpoints |
|---|---|
| Auth and workspace | `POST /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` |
| Team | `GET /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](https://onesend.email/docs/team/) |
| 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 log | `GET /audit-log` (filters: action or prefix such as `member.`, actor, target, since, until) · `GET /audit-log/export` (CSV) |
| Emails | `POST /emails` · `POST /emails/batch` · `GET /emails` · `GET /emails/:id` · `POST /emails/:id/cancel` · `POST /emails/:id/resend` |
| Provider catalog | `GET /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` |
| Routing | `GET/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 reputation | `GET /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 & domains | `GET/POST /domains` · `GET/PATCH/DELETE /domains/:id` (PATCH: `tracking` and `allowedConnections`, see [Tracking per domain](https://onesend.email/docs/domains-and-dns/#per-domain-tracking) and [Which providers send for a domain](https://onesend.email/docs/domains-and-dns/#sending-providers)) · `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](https://onesend.email/docs/domains-and-dns/#using-any-dns-host) and [Receiving email](https://onesend.email/docs/domains-and-dns/#receiving-email) |
| DNS hosts | `GET /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 |
| Templates | `GET/POST /templates` · `GET/PATCH/DELETE /templates/:id` · `POST /templates/:id/render` · `POST /templates/render` · `GET /templates/:id/versions` |
| Gallery | `GET /gallery` · `GET /gallery/:slug` · `GET /gallery/:slug/preview.html` · `POST /gallery/:slug/clone` · `GET /gallery/status` · `GET`/`POST /gallery/submissions` (see [Templates](https://onesend.email/docs/templates/#gallery)) |
| Inbox | `GET/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](https://onesend.email/docs/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 inbox | `POST /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](https://onesend.email/docs/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_…|own|all&accountFolder=…` on `GET /inbox/messages`, `accountId` on `POST /inbox/compose`. See [Unified inbox](https://onesend.email/docs/unified-inbox/) |
| Provider inbound | `GET /inbound-endpoints/providers` · `GET/POST /inbound-endpoints` · `PATCH/DELETE /inbound-endpoints/:id` (admin). See [Unified inbox](https://onesend.email/docs/unified-inbox/#provider-inbound) |
| Calendar | `/calendar/calendars`, `/calendar/events`, invitations and answers, reminders, ICS import and export, the private feed, free/busy. See [Calendar](https://onesend.email/docs/calendar/) |
| Booking pages | `/booking/profile`, `/booking/event-types`, `/booking/bookings`; public pages at `/book/:handle` (outside `/v1`). See [Booking pages](https://onesend.email/docs/booking/) |
| Drive | `/drive/drives`, folders and files, chunked uploads (`/drive/uploads`), versions, Trash, shares and public links (`/share/:token` outside `/v1`), usage. See [Drive](https://onesend.email/docs/drive/) |
| Mail import | `POST /inbox/imports` · chunked uploads · `GET /inbox/imports[/:id]` · `POST /inbox/imports/preview`. See [Importing mail](https://onesend.email/docs/inbox/#importing-mail) |
| License | `GET /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](https://onesend.email/docs/self-hosting/#license-key) |
| Contacts | `GET/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 & segments | `GET/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 forms | `GET/POST /forms` · `GET/PATCH/DELETE /forms/:id` · `GET /forms/:id/embed` · `GET/POST /forms/:id/submissions` · `POST /forms/preview`. See [Signup forms and archive](https://onesend.email/docs/forms-and-archive/) |
| Public archive | `GET/PATCH /archive/settings` · `GET/PUT /campaigns/:id/archive` |
| Campaigns | `GET/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](https://onesend.email/docs/marketing/#ab-testing) |
| Automations | `GET/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](https://onesend.email/docs/automations/) |
| Custom events | `POST /events/track` (Sending only keys allowed) · `GET /events/tracked` |
| Statistics | `GET /statistics/overview` (filters: type, campaign, provider, sending domain, recipient domain, tag, template; compares with the previous period) |
| Conversions | `POST /conversions` · `GET /conversions` · browser: `POST /t/conversion` with a Conversion tracking key (`os_pub_…`) and the `/t/onesend.js` script |
| Suppressions | `GET/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](https://onesend.email/docs/deliverability/#one-suppression-list) |
| Analytics | `GET /analytics/summary` · `GET /analytics/quota` (`pooled.excluded` lists Sandbox, paused and failing connections left out of the pooled totals) · `GET /events` |
| Deliverability | `GET /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](https://onesend.email/docs/deliverability/) |
| Deliverability tools | `POST /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](https://onesend.email/docs/tools/) |
| Keys & webhooks | `GET/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 deletion | `POST /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](https://onesend.email/docs/privacy/) |
| Status page admin | `GET/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](https://onesend.email/docs/status-page/) |
| AI assistant | `GET/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](https://onesend.email/docs/ai/) |

### 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](https://onesend.email/docs/migrate/).
- 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](https://onesend.email/docs/mcp/#remote).
- 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
```http
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"
}
```
```json
{ "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:

```http
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](https://onesend.email/docs/self-hosting/#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](https://onesend.email/docs/domains-and-dns/#sending-providers).


## 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](https://onesend.email/docs/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](https://onesend.email/docs/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.
