---
title: "API reference"
description: "Every endpoint of the OneSend REST API by area: method, path, parameters, request body and response shape, generated from the OpenAPI document."
url: https://onesend.email/docs/api-reference/
---
[Docs](https://onesend.email/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](https://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](https://onesend.email/docs/api-reference/emails/)

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

- [GET`/v1/emails`List emails](https://onesend.email/docs/api-reference/emails/#list-emails)
- [POST`/v1/emails`Send an email](https://onesend.email/docs/api-reference/emails/#send-email)
- [POST`/v1/emails/batch`Send up to 100 emails](https://onesend.email/docs/api-reference/emails/#send-email-batch)
- [GET`/v1/emails/{id}`Get an email with its routing attempts and events](https://onesend.email/docs/api-reference/emails/#get-email)
- [POST`/v1/emails/{id}/cancel`Cancel a scheduled or deferred email](https://onesend.email/docs/api-reference/emails/#cancel-email)
- [POST`/v1/emails/{id}/resend`Send a copy of an email again (new id, same content)](https://onesend.email/docs/api-reference/emails/#resend-email)

### [Sending providers](https://onesend.email/docs/api-reference/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/connections`List connected provider accounts with today's usage](https://onesend.email/docs/api-reference/sending-providers/#list-connections)
- [POST`/v1/connections`Connect a provider account](https://onesend.email/docs/api-reference/sending-providers/#create-connection)
- [GET`/v1/connections/{id}`Get a connection](https://onesend.email/docs/api-reference/sending-providers/#get-connection)
- [PATCH`/v1/connections/{id}`Update a connection (rename, pause, limits, credentials)](https://onesend.email/docs/api-reference/sending-providers/#update-connection)
- [DELETE`/v1/connections/{id}`Disconnect a provider](https://onesend.email/docs/api-reference/sending-providers/#delete-connection)
- [POST`/v1/connections/{id}/test`Check the credentials still work](https://onesend.email/docs/api-reference/sending-providers/#test-connection)
- [GET`/v1/connections/{id}/insights`Health, affinity, webhooks and sync of a connection](https://onesend.email/docs/api-reference/sending-providers/#list-connection-insights)
- [POST`/v1/connections/{id}/health/reset`Put a provider back in rotation](https://onesend.email/docs/api-reference/sending-providers/#reset-connections-health)
- [POST`/v1/connections/{id}/suppressions/sync`Import this provider's suppression list now](https://onesend.email/docs/api-reference/sending-providers/#sync-connections-suppressions)
- [POST`/v1/connections/{id}/rotate-webhook-url`Rotate the provider webhook URL](https://onesend.email/docs/api-reference/sending-providers/#rotate-connection-webhook-url)
- [POST`/v1/connections/{id}/refresh-quota`Re-detect quota from the provider](https://onesend.email/docs/api-reference/sending-providers/#refresh-connection-quota)

### [Provider catalog](https://onesend.email/docs/api-reference/provider-catalog/)

Catalog of supported providers and the credentials each one needs.

- [GET`/v1/providers`Provider catalog](https://onesend.email/docs/api-reference/provider-catalog/#list-providers)

### [Routing](https://onesend.email/docs/api-reference/routing/)

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

- [GET`/v1/policies`List routing policies](https://onesend.email/docs/api-reference/routing/#list-policies)
- [POST`/v1/policies`Create a routing policy](https://onesend.email/docs/api-reference/routing/#create-policy)
- [GET`/v1/policies/{id}`Get a policy](https://onesend.email/docs/api-reference/routing/#get-policy)
- [PATCH`/v1/policies/{id}`Update a policy (reorder steps, caps, rules, fallback)](https://onesend.email/docs/api-reference/routing/#update-policy)
- [DELETE`/v1/policies/{id}`Delete a policy](https://onesend.email/docs/api-reference/routing/#delete-policy)
- [POST`/v1/route/preview`Dry-run: which provider would send this right now, and why the others would not](https://onesend.email/docs/api-reference/routing/#preview-route)

### [Senders & domains](https://onesend.email/docs/api-reference/senders-domains/)

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

- [GET`/v1/domains`List domains with per-provider verification](https://onesend.email/docs/api-reference/senders-domains/#list-domains)
- [POST`/v1/domains`Add a domain once — registered on every provider](https://onesend.email/docs/api-reference/senders-domains/#create-domain)
- [GET`/v1/domains/provider-domains`Domains already set up in your providers](https://onesend.email/docs/api-reference/senders-domains/#list-domain-provider-domains)
- [GET`/v1/domains/{id}`Get a domain and its merged DNS plan](https://onesend.email/docs/api-reference/senders-domains/#get-domain)
- [PATCH`/v1/domains/{id}`Update a domain: tracking and allowed sending providers](https://onesend.email/docs/api-reference/senders-domains/#update-domain)
- [DELETE`/v1/domains/{id}`Remove a domain from OneSend](https://onesend.email/docs/api-reference/senders-domains/#delete-domain)
- [POST`/v1/domains/{id}/verify`Re-check verification on every provider and DNS](https://onesend.email/docs/api-reference/senders-domains/#verify-domain)
- [POST`/v1/domains/{id}/apply-dns`Write the DNS plan through the DNS host connection](https://onesend.email/docs/api-reference/senders-domains/#apply-domain-dns)
- [GET`/v1/domains/{id}/zone`Export the DNS plan as a BIND zone file (text/plain)](https://onesend.email/docs/api-reference/senders-domains/#get-domain-zone)
- [GET`/v1/domains/{id}/dns-setup`DNS setup instructions for the domain's DNS host](https://onesend.email/docs/api-reference/senders-domains/#get-domain-dns-setup)
- [PATCH`/v1/domains/{id}/dns-host`Choose the DNS host or connection for a domain](https://onesend.email/docs/api-reference/senders-domains/#dns-domain-host)
- [POST`/v1/domains/{id}/dns-plan`Preview DNS changes (dry run)](https://onesend.email/docs/api-reference/senders-domains/#dns-domain-plan)
- [POST`/v1/domains/{id}/dns-apply`Apply DNS changes](https://onesend.email/docs/api-reference/senders-domains/#dns-domain-apply)
- [GET`/v1/domains/{id}/diagnostics`Diagnose the DNS records](https://onesend.email/docs/api-reference/senders-domains/#list-domain-diagnostics)
- [GET`/v1/receiving-hosts`Receiving host catalog](https://onesend.email/docs/api-reference/senders-domains/#list-receiving-hosts)
- [GET`/v1/domains/{id}/receiving`Receiving status and records for a domain](https://onesend.email/docs/api-reference/senders-domains/#get-domain-receiving)
- [PATCH`/v1/domains/{id}/receiving`Choose where mail to the domain should arrive](https://onesend.email/docs/api-reference/senders-domains/#receiving-domain)
- [POST`/v1/domains/{id}/receiving/apply`Write the receiving host's MX and SPF records (preview, then confirm)](https://onesend.email/docs/api-reference/senders-domains/#apply-domains-receiving)

### [DNS hosts](https://onesend.email/docs/api-reference/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-hosts`DNS host catalog](https://onesend.email/docs/api-reference/dns-hosts/#list-dns-hosts)
- [GET`/v1/dns-hosts/detect`Detect the DNS host of a domain](https://onesend.email/docs/api-reference/dns-hosts/#get-dns-host-detect)
- [GET`/v1/dns-hosts/connections`List DNS host connections](https://onesend.email/docs/api-reference/dns-hosts/#list-dns-host-connections)
- [POST`/v1/dns-hosts/connections`Connect a DNS host](https://onesend.email/docs/api-reference/dns-hosts/#create-dns-host-connection)
- [GET`/v1/dns-hosts/connections/{id}`Get a DNS host connection](https://onesend.email/docs/api-reference/dns-hosts/#get-dns-host-connection)
- [PATCH`/v1/dns-hosts/connections/{id}`Update a DNS host connection](https://onesend.email/docs/api-reference/dns-hosts/#update-dns-host-connection)
- [DELETE`/v1/dns-hosts/connections/{id}`Delete a DNS host connection](https://onesend.email/docs/api-reference/dns-hosts/#delete-dns-host-connection)
- [POST`/v1/dns-hosts/connections/{id}/test`Test a DNS host connection](https://onesend.email/docs/api-reference/dns-hosts/#test-dns-host-connection)

### [Templates](https://onesend.email/docs/api-reference/templates/)

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

- [GET`/v1/templates`List templates](https://onesend.email/docs/api-reference/templates/#list-templates)
- [POST`/v1/templates`Create a template](https://onesend.email/docs/api-reference/templates/#create-template)
- [GET`/v1/templates/{id}`Get a template (by id or slug)](https://onesend.email/docs/api-reference/templates/#get-template)
- [PATCH`/v1/templates/{id}`Update a template](https://onesend.email/docs/api-reference/templates/#update-template)
- [DELETE`/v1/templates/{id}`Delete a template](https://onesend.email/docs/api-reference/templates/#delete-template)
- [POST`/v1/templates/{id}/render`Render a stored template with variables](https://onesend.email/docs/api-reference/templates/#render-template)
- [POST`/v1/templates/render`Render an ad-hoc template document (no save)](https://onesend.email/docs/api-reference/templates/#render-template-document)
- [GET`/v1/templates/{id}/versions`List versions of a template](https://onesend.email/docs/api-reference/templates/#list-template-versions)

### [Gallery](https://onesend.email/docs/api-reference/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/status`Where this server reads the gallery from, and whether this workspace can share templates](https://onesend.email/docs/api-reference/gallery/#get-gallery-status)
- [GET`/v1/gallery/submissions`This workspace's gallery submissions](https://onesend.email/docs/api-reference/gallery/#list-gallery-submissions)
- [POST`/v1/gallery/submissions`Share a template to the gallery](https://onesend.email/docs/api-reference/gallery/#submit-gallery-template)
- [GET`/v1/gallery`Browse the template gallery](https://onesend.email/docs/api-reference/gallery/#list-gallery-templates)
- [GET`/v1/gallery/{slug}`Get a gallery template with its document, sample data and preview](https://onesend.email/docs/api-reference/gallery/#get-gallery-template)
- [GET`/v1/gallery/{slug}/preview.html`Preview a gallery template](https://onesend.email/docs/api-reference/gallery/#preview-gallery-template)
- [POST`/v1/gallery/{slug}/use`Count a use of a gallery template](https://onesend.email/docs/api-reference/gallery/#count-gallery-template-use)
- [POST`/v1/gallery/{slug}/clone`Copy a gallery template into your workspace](https://onesend.email/docs/api-reference/gallery/#clone-gallery-template)

### [Contacts](https://onesend.email/docs/api-reference/contacts/)

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

- [GET`/v1/contact-attributes`List contact attributes](https://onesend.email/docs/api-reference/contacts/#list-contact-attributes)
- [POST`/v1/contact-attributes`Create a contact attribute](https://onesend.email/docs/api-reference/contacts/#create-contact-attribute)
- [DELETE`/v1/contact-attributes/{key}`Delete a contact attribute](https://onesend.email/docs/api-reference/contacts/#delete-contact-attribute)
- [GET`/v1/contacts`List contacts](https://onesend.email/docs/api-reference/contacts/#list-contacts)
- [POST`/v1/contacts`Create or update a contact (by email)](https://onesend.email/docs/api-reference/contacts/#create-contact)
- [POST`/v1/contacts/bulk`Bulk actions on contacts](https://onesend.email/docs/api-reference/contacts/#bulk-update-contacts)
- [GET`/v1/contacts/export`Export contacts as CSV (streamed)](https://onesend.email/docs/api-reference/contacts/#export-contacts)
- [GET`/v1/contacts/{id}`Get a contact](https://onesend.email/docs/api-reference/contacts/#get-contact)
- [PATCH`/v1/contacts/{id}`Update a contact](https://onesend.email/docs/api-reference/contacts/#update-contact)
- [DELETE`/v1/contacts/{id}`Delete a contact](https://onesend.email/docs/api-reference/contacts/#delete-contact)
- [GET`/v1/contacts/{id}/activity`Contact activity timeline](https://onesend.email/docs/api-reference/contacts/#get-contact-activity)
- [GET`/v1/contacts/{id}/journeys`Automations a contact went through](https://onesend.email/docs/api-reference/contacts/#list-contact-journeys)
- [GET`/v1/contacts/{id}/export`Export a contact's data (GDPR)](https://onesend.email/docs/api-reference/contacts/#get-contact-export)

### [Lists](https://onesend.email/docs/api-reference/lists/)

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

- [GET`/v1/lists`List contact lists](https://onesend.email/docs/api-reference/lists/#list-lists)
- [POST`/v1/lists`Create a list](https://onesend.email/docs/api-reference/lists/#create-list)
- [GET`/v1/lists/{id}`Get a list](https://onesend.email/docs/api-reference/lists/#get-list)
- [PATCH`/v1/lists/{id}`Rename or describe a list](https://onesend.email/docs/api-reference/lists/#update-list)
- [DELETE`/v1/lists/{id}`Delete a list](https://onesend.email/docs/api-reference/lists/#delete-list)

### [Segments](https://onesend.email/docs/api-reference/segments/)

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

- [GET`/v1/segments`List segments (with contact counts)](https://onesend.email/docs/api-reference/segments/#list-segments)
- [POST`/v1/segments`Create a segment](https://onesend.email/docs/api-reference/segments/#create-segment)
- [POST`/v1/segments/preview`Count contacts matching unsaved conditions](https://onesend.email/docs/api-reference/segments/#preview-segment)
- [GET`/v1/segments/{id}`Get a segment](https://onesend.email/docs/api-reference/segments/#get-segment)
- [PATCH`/v1/segments/{id}`Update a segment](https://onesend.email/docs/api-reference/segments/#update-segment)
- [DELETE`/v1/segments/{id}`Delete a segment](https://onesend.email/docs/api-reference/segments/#delete-segment)

### [Imports](https://onesend.email/docs/api-reference/imports/)

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

- [GET`/v1/contacts/import-presets`CSV import presets](https://onesend.email/docs/api-reference/imports/#list-contact-import-presets)
- [GET`/v1/contacts/imports`Import history](https://onesend.email/docs/api-reference/imports/#list-contact-imports)
- [POST`/v1/contacts/imports`Upload a CSV file (step 1)](https://onesend.email/docs/api-reference/imports/#upload-contact-import)
- [GET`/v1/contacts/imports/{id}`Get an import (poll while processing)](https://onesend.email/docs/api-reference/imports/#get-contact-import)
- [POST`/v1/contacts/imports/{id}/start`Map columns and start the import (step 2)](https://onesend.email/docs/api-reference/imports/#start-contact-import)
- [GET`/v1/contacts/imports/{id}/errors.csv`Download rows that were not imported (CSV)](https://onesend.email/docs/api-reference/imports/#get-contact-import-errors)

### [Campaigns](https://onesend.email/docs/api-reference/campaigns/)

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

- [GET`/v1/campaigns`List campaigns with headline stats](https://onesend.email/docs/api-reference/campaigns/#list-campaigns)
- [POST`/v1/campaigns`Create a draft campaign](https://onesend.email/docs/api-reference/campaigns/#create-campaign)
- [GET`/v1/campaigns/{id}`Get a campaign](https://onesend.email/docs/api-reference/campaigns/#get-campaign)
- [PATCH`/v1/campaigns/{id}`Edit a campaign](https://onesend.email/docs/api-reference/campaigns/#update-campaign)
- [DELETE`/v1/campaigns/{id}`Delete a campaign](https://onesend.email/docs/api-reference/campaigns/#delete-campaign)
- [GET`/v1/campaigns/{id}/check`Check a campaign before sending](https://onesend.email/docs/api-reference/campaigns/#get-campaign-check)
- [POST`/v1/campaigns/{id}/duplicate`Duplicate as a new draft](https://onesend.email/docs/api-reference/campaigns/#duplicate-campaign)
- [POST`/v1/campaigns/{id}/test`Send a test email](https://onesend.email/docs/api-reference/campaigns/#test-campaign)
- [POST`/v1/campaigns/{id}/schedule`Schedule, or send now](https://onesend.email/docs/api-reference/campaigns/#schedule-campaign)
- [POST`/v1/campaigns/{id}/pause`Pause sending (emails not yet handed to a provider are held)](https://onesend.email/docs/api-reference/campaigns/#pause-campaign)
- [POST`/v1/campaigns/{id}/resume`Resume a paused campaign](https://onesend.email/docs/api-reference/campaigns/#resume-campaign)
- [POST`/v1/campaigns/{id}/cancel`Cancel (emails not yet handed to a provider are dropped)](https://onesend.email/docs/api-reference/campaigns/#cancel-campaign)
- [GET`/v1/campaigns/{id}/ab-test`A/B test results](https://onesend.email/docs/api-reference/campaigns/#get-campaign-ab-test)
- [POST`/v1/campaigns/{id}/ab-test/winner`Pick the A/B test winner](https://onesend.email/docs/api-reference/campaigns/#pick-campaign-ab-winner)
- [GET`/v1/campaigns/{id}/report`Campaign report](https://onesend.email/docs/api-reference/campaigns/#get-campaign-report)
- [GET`/v1/campaigns/{id}/recipients`Recipient activity (JSON or CSV)](https://onesend.email/docs/api-reference/campaigns/#list-campaign-recipients)
- [GET`/v1/campaigns/{id}/safeguards`Safeguards that apply to a campaign](https://onesend.email/docs/api-reference/campaigns/#list-campaign-safeguards)

### [Automations](https://onesend.email/docs/api-reference/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/automations`List automations](https://onesend.email/docs/api-reference/automations/#list-automations)
- [POST`/v1/automations`Create an automation](https://onesend.email/docs/api-reference/automations/#create-automation)
- [GET`/v1/automations/recipes`Automation recipes](https://onesend.email/docs/api-reference/automations/#list-automation-recipes)
- [GET`/v1/automations/{id}`Get an automation](https://onesend.email/docs/api-reference/automations/#get-automation)
- [PATCH`/v1/automations/{id}`Edit an automation](https://onesend.email/docs/api-reference/automations/#update-automation)
- [DELETE`/v1/automations/{id}`Delete an automation](https://onesend.email/docs/api-reference/automations/#delete-automation)
- [POST`/v1/automations/{id}/validate`Check an automation](https://onesend.email/docs/api-reference/automations/#validate-automation)
- [POST`/v1/automations/{id}/activate`Activate (or resume) an automation](https://onesend.email/docs/api-reference/automations/#activate-automation)
- [POST`/v1/automations/{id}/pause`Pause an automation](https://onesend.email/docs/api-reference/automations/#pause-automation)
- [POST`/v1/automations/{id}/stop`Stop an automation](https://onesend.email/docs/api-reference/automations/#stop-automation)
- [POST`/v1/automations/{id}/enroll`Enroll contacts](https://onesend.email/docs/api-reference/automations/#enroll-automation)
- [POST`/v1/automations/{id}/test`Test with one contact](https://onesend.email/docs/api-reference/automations/#test-automation)
- [GET`/v1/automations/{id}/report`Automation report](https://onesend.email/docs/api-reference/automations/#get-automation-report)
- [GET`/v1/automations/{id}/runs`List runs](https://onesend.email/docs/api-reference/automations/#list-automation-runs)
- [GET`/v1/automations/{id}/runs/{runId}`Get a run with its step history](https://onesend.email/docs/api-reference/automations/#get-automation-run)
- [POST`/v1/automations/{id}/runs/{runId}/exit`Remove a contact from an automation](https://onesend.email/docs/api-reference/automations/#exit-automation-run)
- [GET`/v1/automations/{id}/versions`Published versions](https://onesend.email/docs/api-reference/automations/#list-automation-versions)
- [GET`/v1/automations/{id}/signing-secret`Webhook step signing secret](https://onesend.email/docs/api-reference/automations/#get-automation-signing-secret)
- [POST`/v1/automations/{id}/rotate-secret`Rotate the signing secret](https://onesend.email/docs/api-reference/automations/#rotate-automation-secret)

### [Events](https://onesend.email/docs/api-reference/events/)

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

- [POST`/v1/events/track`Track a custom event](https://onesend.email/docs/api-reference/events/#track-event)
- [GET`/v1/events/tracked`List tracked events](https://onesend.email/docs/api-reference/events/#list-tracked-events)

### [Forms](https://onesend.email/docs/api-reference/forms/)

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

- [GET`/v1/forms`List signup forms](https://onesend.email/docs/api-reference/forms/#list-forms)
- [POST`/v1/forms`Create a signup form](https://onesend.email/docs/api-reference/forms/#create-form)
- [POST`/v1/forms/preview`Preview a form](https://onesend.email/docs/api-reference/forms/#preview-forms)
- [GET`/v1/forms/{id}`Get a signup form](https://onesend.email/docs/api-reference/forms/#get-form)
- [PATCH`/v1/forms/{id}`Update a signup form](https://onesend.email/docs/api-reference/forms/#update-form)
- [DELETE`/v1/forms/{id}`Delete a signup form](https://onesend.email/docs/api-reference/forms/#delete-form)
- [GET`/v1/forms/{id}/embed`Embed code for a form](https://onesend.email/docs/api-reference/forms/#get-form-embed)
- [GET`/v1/forms/{id}/submissions`List form submissions](https://onesend.email/docs/api-reference/forms/#list-form-submissions)
- [POST`/v1/forms/{id}/submissions`Submit a form from your server](https://onesend.email/docs/api-reference/forms/#submissions-form)

### [Archive](https://onesend.email/docs/api-reference/archive/)

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

- [GET`/v1/archive/settings`Public archive settings](https://onesend.email/docs/api-reference/archive/#list-archive-settings)
- [PATCH`/v1/archive/settings`Update public archive settings](https://onesend.email/docs/api-reference/archive/#update-archive-setting)
- [GET`/v1/campaigns/{id}/archive`Archive status of a campaign](https://onesend.email/docs/api-reference/archive/#get-campaign-archive)
- [PUT`/v1/campaigns/{id}/archive`Show or hide a campaign in the public archive](https://onesend.email/docs/api-reference/archive/#archive-campaign)

### [Statistics](https://onesend.email/docs/api-reference/statistics/)

Delivery and engagement statistics with filters.

- [GET`/v1/statistics/overview`Email statistics with filters and previous-period comparison](https://onesend.email/docs/api-reference/statistics/#get-statistics-overview)
- [GET`/v1/statistics/breakdown`Email by mailbox provider and by category](https://onesend.email/docs/api-reference/statistics/#get-statistics-breakdown)

### [Deliverability](https://onesend.email/docs/api-reference/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/deliverability`Deliverability overview](https://onesend.email/docs/api-reference/deliverability/#get-deliverability)
- [GET`/v1/deliverability/alerts`Deliverability alerts for the dashboard](https://onesend.email/docs/api-reference/deliverability/#list-deliverability-alerts)
- [GET`/v1/deliverability/settings`Deliverability settings](https://onesend.email/docs/api-reference/deliverability/#list-deliverability-settings)
- [PATCH`/v1/deliverability/settings`Change deliverability settings](https://onesend.email/docs/api-reference/deliverability/#update-deliverability-setting)
- [GET`/v1/deliverability/guard`Workspace guard](https://onesend.email/docs/api-reference/deliverability/#get-deliverability-guard)
- [POST`/v1/deliverability/acknowledge`Acknowledge the workspace guard](https://onesend.email/docs/api-reference/deliverability/#acknowledge-deliverability)
- [GET`/v1/deliverability/warmup`Warm-up per sending domain](https://onesend.email/docs/api-reference/deliverability/#get-deliverability-warmup)
- [PATCH`/v1/deliverability/warmup/{domain}`Change the warm-up of a sending domain](https://onesend.email/docs/api-reference/deliverability/#update-deliverability-warmup)
- [GET`/v1/deliverability/best-time`Best time to send](https://onesend.email/docs/api-reference/deliverability/#get-deliverability-best-time)
- [POST`/v1/deliverability/quality/check`Check address quality](https://onesend.email/docs/api-reference/deliverability/#check-deliverability-quality)
- [POST`/v1/deliverability/quality/recheck`Re-check the address quality of every contact](https://onesend.email/docs/api-reference/deliverability/#recheck-deliverability-quality)
- [POST`/v1/deliverability/inactive/restore`Restore inactive contacts](https://onesend.email/docs/api-reference/deliverability/#restore-deliverability-inactive)
- [POST`/v1/deliverability/sunset/run`Run sunsetting now](https://onesend.email/docs/api-reference/deliverability/#run-deliverability-sunset)

### [Conversions](https://onesend.email/docs/api-reference/conversions/)

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

- [GET`/v1/conversions`List conversions](https://onesend.email/docs/api-reference/conversions/#list-conversions)
- [POST`/v1/conversions`Record a conversion](https://onesend.email/docs/api-reference/conversions/#create-conversion)

### [Suppressions](https://onesend.email/docs/api-reference/suppressions/)

One suppression list shared by every provider.

- [GET`/v1/suppressions`List suppressed addresses (shared across every provider)](https://onesend.email/docs/api-reference/suppressions/#list-suppressions)
- [POST`/v1/suppressions`Suppress an address](https://onesend.email/docs/api-reference/suppressions/#create-suppression)
- [GET`/v1/suppressions/stats`Suppression counts by reason, origin and provider connection](https://onesend.email/docs/api-reference/suppressions/#list-suppression-stats)
- [GET`/v1/suppressions/sync`Provider suppression sync status per connection](https://onesend.email/docs/api-reference/suppressions/#get-suppression-sync)
- [POST`/v1/suppressions/sync`Import provider suppression lists now](https://onesend.email/docs/api-reference/suppressions/#sync-suppressions)
- [DELETE`/v1/suppressions/{email}`Remove an address from the suppression list](https://onesend.email/docs/api-reference/suppressions/#delete-suppression)

### [Analytics](https://onesend.email/docs/api-reference/analytics/)

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

- [GET`/v1/analytics/summary`Delivery, engagement and failover analytics](https://onesend.email/docs/api-reference/analytics/#get-analytics-summary)
- [GET`/v1/analytics/quota`Pooled and per-provider quota for today](https://onesend.email/docs/api-reference/analytics/#get-analytics-quota)
- [GET`/v1/events`Event log](https://onesend.email/docs/api-reference/analytics/#list-events)

### [Webhooks](https://onesend.email/docs/api-reference/webhooks/)

Outgoing events to your app, Slack or Discord.

- [GET`/v1/webhooks`List webhook endpoints](https://onesend.email/docs/api-reference/webhooks/#list-webhooks)
- [POST`/v1/webhooks`Register a webhook endpoint](https://onesend.email/docs/api-reference/webhooks/#create-webhook)
- [DELETE`/v1/webhooks/{id}`Delete a webhook endpoint](https://onesend.email/docs/api-reference/webhooks/#delete-webhook)
- [POST`/v1/webhooks/{id}/rotate-secret`Rotate the signing secret](https://onesend.email/docs/api-reference/webhooks/#rotate-webhook-secret)
- [POST`/v1/webhooks/{id}/test`Send a test event now](https://onesend.email/docs/api-reference/webhooks/#test-webhook)

### [API keys](https://onesend.email/docs/api-reference/api-keys/)

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

- [GET`/v1/api-keys`List API keys](https://onesend.email/docs/api-reference/api-keys/#list-api-keys)
- [POST`/v1/api-keys`Create an API key](https://onesend.email/docs/api-reference/api-keys/#create-api-key)
- [PATCH`/v1/api-keys/{id}`Update an API key](https://onesend.email/docs/api-reference/api-keys/#update-api-key)
- [DELETE`/v1/api-keys/{id}`Revoke an API key](https://onesend.email/docs/api-reference/api-keys/#delete-api-key)
- [POST`/v1/api-keys/{id}/rotate`Rotate an API key](https://onesend.email/docs/api-reference/api-keys/#rotate-api-key)

### [AI assistant](https://onesend.email/docs/api-reference/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/settings`AI settings](https://onesend.email/docs/api-reference/ai-assistant/#list-ai-settings)
- [PATCH`/v1/ai/settings`Update AI settings](https://onesend.email/docs/api-reference/ai-assistant/#update-ai-setting)
- [GET`/v1/ai/connections`List AI connections](https://onesend.email/docs/api-reference/ai-assistant/#list-ai-connections)
- [POST`/v1/ai/connections`Add an AI connection](https://onesend.email/docs/api-reference/ai-assistant/#create-ai-connection)
- [GET`/v1/ai/connections/{id}`Get an AI connection](https://onesend.email/docs/api-reference/ai-assistant/#get-ai-connection)
- [PATCH`/v1/ai/connections/{id}`Update an AI connection](https://onesend.email/docs/api-reference/ai-assistant/#update-ai-connection)
- [DELETE`/v1/ai/connections/{id}`Delete an AI connection](https://onesend.email/docs/api-reference/ai-assistant/#delete-ai-connection)
- [POST`/v1/ai/connections/{id}/test`Test an AI connection](https://onesend.email/docs/api-reference/ai-assistant/#test-ai-connection)
- [GET`/v1/ai/notes`List workspace notes](https://onesend.email/docs/api-reference/ai-assistant/#list-ai-notes)
- [POST`/v1/ai/notes`Add a note](https://onesend.email/docs/api-reference/ai-assistant/#create-ai-note)
- [GET`/v1/ai/notes/{id}`Get a note](https://onesend.email/docs/api-reference/ai-assistant/#get-ai-note)
- [PATCH`/v1/ai/notes/{id}`Update a note](https://onesend.email/docs/api-reference/ai-assistant/#update-ai-note)
- [DELETE`/v1/ai/notes/{id}`Delete a note](https://onesend.email/docs/api-reference/ai-assistant/#delete-ai-note)
- [GET`/v1/ai/usage`AI usage](https://onesend.email/docs/api-reference/ai-assistant/#get-ai-usage)
- [POST`/v1/ai/summarize`Summarize a thread](https://onesend.email/docs/api-reference/ai-assistant/#summarize-ai)
- [POST`/v1/ai/subjects`Suggest subject lines and preview text](https://onesend.email/docs/api-reference/ai-assistant/#create-ai-subject)
- [POST`/v1/ai/generate-template`Generate a template](https://onesend.email/docs/api-reference/ai-assistant/#generate-template-ai)
- [POST`/v1/ai/rewrite`Rewrite text](https://onesend.email/docs/api-reference/ai-assistant/#rewrite-ai)
- [POST`/v1/ai/explain-failure`Explain a failed email](https://onesend.email/docs/api-reference/ai-assistant/#explain-failure-ai)
- [POST`/v1/ai/deliverability-review`Review deliverability](https://onesend.email/docs/api-reference/ai-assistant/#deliverability-review-ai)
- [POST`/v1/ai/spam-check`Check content for spam before sending](https://onesend.email/docs/api-reference/ai-assistant/#spam-check-ai)
- [POST`/v1/ai/write-campaign`Write a campaign from a goal](https://onesend.email/docs/api-reference/ai-assistant/#write-campaign-ai)
- [POST`/v1/ai/translate-template`Translate a template](https://onesend.email/docs/api-reference/ai-assistant/#translate-template-ai)

### [Workspace](https://onesend.email/docs/api-reference/workspace/)

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

- [GET`/v1/workspace`Workspace settings (tracking, sandbox, brand) and SMTP details](https://onesend.email/docs/api-reference/workspace/#get-workspace)
- [PATCH`/v1/workspace`Update workspace settings](https://onesend.email/docs/api-reference/workspace/#update-workspace)
- [DELETE`/v1/workspace`Delete the workspace](https://onesend.email/docs/api-reference/workspace/#delete-workspace)
- [POST`/v1/workspace/export`Export all workspace data](https://onesend.email/docs/api-reference/workspace/#export-workspace)
- [GET`/v1/workspace/exports`List data exports](https://onesend.email/docs/api-reference/workspace/#list-workspace-exports)
- [GET`/v1/workspace/exports/{id}`Get a data export](https://onesend.email/docs/api-reference/workspace/#get-workspace-export)
- [GET`/v1/workspace/exports/{id}/download`Download a data export](https://onesend.email/docs/api-reference/workspace/#get-workspace-export-download)
- [GET`/v1/workspace/deletion`Workspace deletion status](https://onesend.email/docs/api-reference/workspace/#get-workspace-deletion)
- [POST`/v1/workspace/deletion/cancel`Cancel the workspace deletion](https://onesend.email/docs/api-reference/workspace/#cancel-workspace-deletion)

### [Auth](https://onesend.email/docs/api-reference/auth/)

Dashboard accounts and session tokens.

- [POST`/v1/auth/signup`Create an account](https://onesend.email/docs/api-reference/auth/#signup)
- [POST`/v1/auth/login`Sign in](https://onesend.email/docs/api-reference/auth/#login)
- [POST`/v1/auth/logout`Sign out (revoke the session and clear the cookie)](https://onesend.email/docs/api-reference/auth/#logout)
- [GET`/v1/auth/me`Current user, workspace and credentials](https://onesend.email/docs/api-reference/auth/#get-current-user)
- [POST`/v1/auth/workspace`Switch the current workspace](https://onesend.email/docs/api-reference/auth/#workspace-auth)
- [POST`/v1/auth/login/2fa`Sign in: second step](https://onesend.email/docs/api-reference/auth/#2fa-auth-login)
- [POST`/v1/auth/password/forgot`Request a password reset link](https://onesend.email/docs/api-reference/auth/#forgot-auth-password)
- [POST`/v1/auth/password/check`Check a password reset link](https://onesend.email/docs/api-reference/auth/#check-auth-password)
- [POST`/v1/auth/password/reset`Set a new password with a reset link](https://onesend.email/docs/api-reference/auth/#reset-auth-password)
- [GET`/v1/setup/status`First-run status](https://onesend.email/docs/api-reference/auth/#get-setup-status)

### [Account](https://onesend.email/docs/api-reference/account/)

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

- [GET`/v1/account`Your account](https://onesend.email/docs/api-reference/account/#get-account)
- [PATCH`/v1/account`Update your profile](https://onesend.email/docs/api-reference/account/#update-account)
- [DELETE`/v1/account`Delete your account](https://onesend.email/docs/api-reference/account/#delete-account)
- [POST`/v1/account/password`Change your password](https://onesend.email/docs/api-reference/account/#password-account)
- [POST`/v1/account/email`Change your email address](https://onesend.email/docs/api-reference/account/#email-account)
- [POST`/v1/auth/email/confirm`Confirm an email change](https://onesend.email/docs/api-reference/account/#confirm-auth-email)
- [POST`/v1/account/email-verification`Verify your email address](https://onesend.email/docs/api-reference/account/#email-verification-account)
- [GET`/v1/account/sessions`List your active sessions](https://onesend.email/docs/api-reference/account/#list-account-sessions)
- [DELETE`/v1/account/sessions/{id}`Revoke a session](https://onesend.email/docs/api-reference/account/#delete-account-session)
- [POST`/v1/account/sessions/revoke-others`Sign out everywhere else](https://onesend.email/docs/api-reference/account/#create-account-session-revoke-other)
- [POST`/v1/account/2fa/setup`Start two-factor setup](https://onesend.email/docs/api-reference/account/#setup-account2fa)
- [POST`/v1/account/2fa/enable`Turn on two-factor authentication](https://onesend.email/docs/api-reference/account/#enable-account2fa)
- [POST`/v1/account/2fa/disable`Turn off two-factor authentication](https://onesend.email/docs/api-reference/account/#disable-account2fa)
- [POST`/v1/account/2fa/recovery-codes`New recovery codes](https://onesend.email/docs/api-reference/account/#create-account2fa-recovery-code)
- [POST`/v1/auth/delete-account`Delete an account without a workspace](https://onesend.email/docs/api-reference/account/#delete-account-auth)

### [Team](https://onesend.email/docs/api-reference/team/)

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

- [POST`/v1/auth/invitation`Look up an invitation](https://onesend.email/docs/api-reference/team/#invitation-auth)
- [POST`/v1/auth/invitation/accept`Accept an invitation](https://onesend.email/docs/api-reference/team/#accept-auth-invitation)
- [GET`/v1/team/members`List workspace members](https://onesend.email/docs/api-reference/team/#list-team-members)
- [PATCH`/v1/team/members/{userId}`Change a member's role](https://onesend.email/docs/api-reference/team/#update-team-member)
- [DELETE`/v1/team/members/{userId}`Remove a member](https://onesend.email/docs/api-reference/team/#delete-team-member)
- [POST`/v1/team/leave`Leave the current workspace](https://onesend.email/docs/api-reference/team/#leave-team)
- [POST`/v1/team/transfer-ownership`Transfer ownership to another member](https://onesend.email/docs/api-reference/team/#transfer-ownership-team)
- [GET`/v1/team/invitations`List invitations](https://onesend.email/docs/api-reference/team/#list-team-invitations)
- [POST`/v1/team/invitations`Invite someone by email](https://onesend.email/docs/api-reference/team/#create-team-invitation)
- [POST`/v1/team/invitations/{id}/resend`Resend an invitation](https://onesend.email/docs/api-reference/team/#resend-team-invitation)
- [DELETE`/v1/team/invitations/{id}`Revoke an invitation](https://onesend.email/docs/api-reference/team/#delete-team-invitation)
- [GET`/v1/team/settings`Team security settings](https://onesend.email/docs/api-reference/team/#list-team-settings)
- [PATCH`/v1/team/settings`Require two-factor authentication](https://onesend.email/docs/api-reference/team/#update-team-setting)

### [Audit log](https://onesend.email/docs/api-reference/audit-log/)

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

- [GET`/v1/audit-log`List audit log entries](https://onesend.email/docs/api-reference/audit-log/#get-audit-log)
- [GET`/v1/audit-log/export`Export the audit log as CSV](https://onesend.email/docs/api-reference/audit-log/#get-audit-log-export)

### [Admin](https://onesend.email/docs/api-reference/admin/)

Instance administration for people listed in ONESEND\_ADMIN\_EMAILS: status page incidents and self-checks.

- [GET`/v1/admin/status-incidents`List status page incidents](https://onesend.email/docs/api-reference/admin/#list-admin-status-incidents)
- [POST`/v1/admin/status-incidents`Post a status page incident](https://onesend.email/docs/api-reference/admin/#create-admin-status-incident)
- [PATCH`/v1/admin/status-incidents/{id}`Update a status page incident](https://onesend.email/docs/api-reference/admin/#update-admin-status-incident)
- [DELETE`/v1/admin/status-incidents/{id}`Delete a status page incident](https://onesend.email/docs/api-reference/admin/#delete-admin-status-incident)
- [POST`/v1/admin/status-checks/run`Run the status self-checks now](https://onesend.email/docs/api-reference/admin/#run-admin-status-checks)

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

- [POST`/v1/tools/dns`Check the email DNS records of any domain](https://onesend.email/docs/api-reference/tools/#check-dns)
- [POST`/v1/tools/dmarc`Generate a DMARC record](https://onesend.email/docs/api-reference/tools/#generate-dmarc-record)
- [POST`/v1/tools/spf`Build an SPF record](https://onesend.email/docs/api-reference/tools/#build-spf-record)
- [POST`/v1/tools/headers`Analyze email headers](https://onesend.email/docs/api-reference/tools/#analyze-headers)
- [POST`/v1/tools/address`Check email addresses](https://onesend.email/docs/api-reference/tools/#check-address)
- [POST`/v1/tools/content`Check email content before sending](https://onesend.email/docs/api-reference/tools/#check-content)

### [Compatibility](https://onesend.email/docs/api-reference/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/emails`Send an email (Resend-compatible)](https://onesend.email/docs/api-reference/compatibility/#compat-resend-send-email)
- [POST`/compat/resend/emails/batch`Send up to 100 emails (Resend-compatible)](https://onesend.email/docs/api-reference/compatibility/#compat-resend-send-batch)
- [POST`/compat/sendgrid/v3/mail/send`Send email (SendGrid v3-compatible)](https://onesend.email/docs/api-reference/compatibility/#compat-sendgrid-mail-send)
- [POST`/compat/postmark/email`Send an email (Postmark-compatible)](https://onesend.email/docs/api-reference/compatibility/#compat-postmark-send-email)
- [POST`/compat/postmark/email/withTemplate`Send with a template (Postmark-compatible)](https://onesend.email/docs/api-reference/compatibility/#compat-postmark-send-with-template)
- [POST`/compat/postmark/email/batch`Send up to 500 emails (Postmark-compatible)](https://onesend.email/docs/api-reference/compatibility/#compat-postmark-send-batch)
- [POST`/compat/postmark/email/batchWithTemplates`Send up to 500 emails with templates (Postmark-compatible)](https://onesend.email/docs/api-reference/compatibility/#compat-postmark-send-batch-with-templates)

### [Public endpoints](https://onesend.email/docs/api-reference/public-endpoints/)

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

- [POST`/t/conversion`Record a conversion from a web page](https://onesend.email/docs/api-reference/public-endpoints/#record-browser-conversion)
- [GET`/t/onesend.js`Conversion tracking script](https://onesend.email/docs/api-reference/public-endpoints/#get-conversion-script)
- [POST`/hooks/{provider}/{connectionId}/{token}`Receive a provider webhook](https://onesend.email/docs/api-reference/public-endpoints/#receive-provider-webhook)
- [GET`/healthz`Health check](https://onesend.email/docs/api-reference/public-endpoints/#get-health)

### [License](https://onesend.email/docs/api-reference/license/)

- [GET`/v1/license`License status of this server](https://onesend.email/docs/api-reference/license/#get-license)
- [POST`/v1/license`Activate a license key on this server](https://onesend.email/docs/api-reference/license/#license)
- [DELETE`/v1/license`Free the license key for another installation](https://onesend.email/docs/api-reference/license/#delete-license)
- [POST`/v1/license/refresh`Check the license with the license server now](https://onesend.email/docs/api-reference/license/#refresh-license)
- [POST`/v1/license/free-other`Free a seat taken by another installation](https://onesend.email/docs/api-reference/license/#free-other-license)

### [Connected apps](https://onesend.email/docs/api-reference/connected-apps/)

- [GET`/v1/oauth/requests/{id}`An app asking to connect (consent screen)](https://onesend.email/docs/api-reference/connected-apps/#get-oauth-request)
- [POST`/v1/oauth/requests/{id}/decision`Approve or deny an app](https://onesend.email/docs/api-reference/connected-apps/#decision-oauth-request)
- [GET`/v1/oauth/grants`Connected apps](https://onesend.email/docs/api-reference/connected-apps/#list-oauth-grants)
- [DELETE`/v1/oauth/grants/{id}`Disconnect an app](https://onesend.email/docs/api-reference/connected-apps/#delete-oauth-grant)

### [Security](https://onesend.email/docs/api-reference/security/)

- [GET`/v1/security/alerts`Security alerts not acknowledged yet](https://onesend.email/docs/api-reference/security/#list-security-alerts)
- [POST`/v1/security/alerts/acknowledge`Acknowledge the security alerts](https://onesend.email/docs/api-reference/security/#acknowledge-security-alerts)
