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.
| From | Guide | Drop-in endpoint |
|---|---|---|
| Resend | resend.md | POST /compat/resend/emails |
| SendGrid | sendgrid.md | POST /compat/sendgrid/v3/mail/send |
| Postmark | postmark.md | POST /compat/postmark/email |
| Mailgun | mailgun.md | None: use /v1/emails or SMTP |
| Amazon SES | amazon-ses.md | None: use /v1/emails or SMTP |
| Gmail SMTP | gmail-smtp.md | SMTP 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-Fieldsresponse header. Fields it does not know are ignored the same way. X-OneSend-Type: broadcaston any compat request sends the email as marketing: OneSend addsList-Unsubscribeheaders 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
/docsunder 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
- Run OneSend and create the workspace (Getting started).
- 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.
- 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. - Create an API key under Developers → API keys. Start with a test key (
os_test_…): sends are logged assandboxedand never delivered. - Point a staging build at OneSend (compat endpoint or native API) with the test key and check Logs.
- 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.
- 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.txtUse
"reason":"complaint"or"unsubscribe"(and"scope":"broadcast"for marketing-only unsubscribes) for the other lists. Managing suppressions needs a live key. - 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.
- Add more providers (optional) and order them under Routing, so a provider outage or daily limit fails over instead of failing.
- Tighten DMARC once reports show every provider passes: move from
p=nonetoquarantine, thenreject(Deliverability tools → DMARC generator).