---
title: "Migrating to OneSend"
description: "OneSend sends through provider accounts you connect. Moving from Resend, SendGrid, Postmark, Mailgun, Amazon SES or Gmail SMTP; compatibility endpoints and cutover checklist."
url: https://onesend.email/docs/migrate/
---
# 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](https://onesend.email/docs/migrate/resend/) | `POST /compat/resend/emails` |
| SendGrid | [sendgrid.md](https://onesend.email/docs/migrate/sendgrid/) | `POST /compat/sendgrid/v3/mail/send` |
| Postmark | [postmark.md](https://onesend.email/docs/migrate/postmark/) | `POST /compat/postmark/email` |
| Mailgun | [mailgun.md](https://onesend.email/docs/migrate/mailgun/) | None: use `/v1/emails` or SMTP |
| Amazon SES | [amazon-ses.md](https://onesend.email/docs/migrate/amazon-ses/) | None: use `/v1/emails` or SMTP |
| Gmail SMTP | [gmail-smtp.md](https://onesend.email/docs/migrate/gmail-smtp/) | 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-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](https://onesend.email/docs/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](https://onesend.email/docs/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:

   ```bash
   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**).
