Docs / Sending and domains

Migrating to OneSend

OneSend sends through provider accounts you connect. Moving an app to OneSend does not mean leaving your current provider: connect it as the first sending provider, keep its DNS records, and add other providers behind it for failover and more daily capacity.

FromGuideDrop-in endpoint
Resendresend.mdPOST /compat/resend/emails
SendGridsendgrid.mdPOST /compat/sendgrid/v3/mail/send
Postmarkpostmark.mdPOST /compat/postmark/email
Mailgunmailgun.mdNone: use /v1/emails or SMTP
Amazon SESamazon-ses.mdNone: use /v1/emails or SMTP
Gmail SMTPgmail-smtp.mdSMTP ingress

How the compatibility endpoints work

The /compat/* endpoints accept the request body that provider's API takes, authenticate a OneSend API key the way that provider's SDKs pass their key, and return that provider's response and error shapes. Each request becomes one or more normal OneSend emails: routing policy, failover, suppressions, tracking, logs and webhooks all apply, exactly as for POST /v1/emails.

  • Point the provider's SDK or HTTP client at your OneSend server (the base URL ends in /compat/<provider>), and replace the provider key with a OneSend API key (Sending only or Full access).
  • Fields that OneSend accepts but cannot apply are listed in the X-OneSend-Ignored-Fields response header. Fields it does not know are ignored the same way.
  • X-OneSend-Type: broadcast on any compat request sends the email as marketing: OneSend adds List-Unsubscribe headers and routes only through providers allowed for campaigns.
  • Template ids in compat payloads refer to OneSend templates (id or slug). Recreate the templates you use in OneSend, or render them in your app.
  • Request bodies are limited to 15 MB (attachments are base64).
  • The endpoints are listed in the API reference at /docs under Compatibility.

The compat endpoints are for moving quickly. Once moved, the native API (/v1/emails, the TypeScript SDK in packages/sdk or the Python SDK in packages/sdk-python) gives you everything: routing policy per send, templates with conditional styling, tags, metadata and per-email tracking settings.

General cutover checklist

  1. Run OneSend and create the workspace (Getting started).
  2. Connect your current provider under Sending providers with an API key that can send and manage domains. A new workspace starts with the Sandbox provider; it is turned off in the default routing policy once a real provider is connected.
  3. Add your sending domain under Senders & domains. OneSend registers it with each connected provider and shows the merged DNS plan. For the provider you already use, its existing DKIM and return-path records stay as they are. Add the ownership record _onesend-verify.<domain> and any records for newly connected providers. Run Deliverability tools → DNS check on the domain to confirm SPF stays within 10 lookups.
  4. Create an API key under Developers → API keys. Start with a test key (os_test_…): sends are logged as sandboxed and never delivered.
  5. Point a staging build at OneSend (compat endpoint or native API) with the test key and check Logs.
  6. Recreate webhooks: your app's delivery and bounce webhooks now come from OneSend (Developers → Webhooks, see Webhooks). OneSend registers its own webhook with each connected provider to receive their events.
  7. Import suppressions (bounces, complaints, unsubscribes) from the old provider. See the provider guide for the export; then add each address:
    while read -r email; do
      curl -s -X POST "$ONESEND_BASE_URL/v1/suppressions" \
        -H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
        -d "{\"email\":\"$email\",\"reason\":\"hard_bounce\"}" > /dev/null
    done < bounces.txt

    Use "reason":"complaint" or "unsubscribe" (and "scope":"broadcast" for marketing-only unsubscribes) for the other lists. Managing suppressions needs a live key.

  8. Switch production to a live key. Watch Logs and Statistics for the first day. Keep the old provider's API key valid until you have confirmed delivery.
  9. Add more providers (optional) and order them under Routing, so a provider outage or daily limit fails over instead of failing.
  10. Tighten DMARC once reports show every provider passes: move from p=none to quarantine, then reject (Deliverability tools → DMARC generator).