---
title: "Migrating from Mailgun"
description: "OneSend has no Mailgun-compatible endpoint. Mailgun's send API takes form data and its SDKs build URLs per domain, so the change is small but needs code: use POST /v1/emails, an SDK, or SMTP ingress."
url: https://onesend.email/docs/migrate/mailgun/
---
# Migrating from Mailgun

OneSend has no Mailgun-compatible endpoint. Mailgun's send API takes form data and its SDKs build URLs per domain, so the change is small but needs code: use `POST /v1/emails`, an SDK, or SMTP ingress. You can keep sending through your Mailgun account by connecting it under **Sending providers** (API key, region and sending domain).

## Field mapping

`POST /v3/<domain>/messages` (form fields) to `POST /v1/emails` (JSON):

| Mailgun | OneSend | Notes |
|---|---|---|
| `from`, `to`, `cc`, `bcc`, `subject`, `text`, `html` | same | Mailgun's comma-separated `to` becomes a list. |
| `h:Reply-To` | `replyTo` | |
| `h:<Header>` | `headers: { "<Header>": "…" }` | |
| `o:tag` (repeatable) | `tags` | |
| `v:<name>` / `h:X-Mailgun-Variables` | `metadata` | String values. |
| `o:deliverytime` | `scheduledAt` | ISO 8601 with an offset instead of RFC 2822. |
| `o:tracking-opens`, `o:tracking-clicks` | `tracking: { opens, clicks }` | |
| `o:testmode` | a test key (`os_test_…`) | Logged as `sandboxed`, never delivered. |
| `template` + `t:variables` | `template` + `variables` | Recreate the template in OneSend; `{{variable}}` syntax is close to Handlebars. |
| `recipient-variables` (batch sending) | `POST /v1/emails/batch` with one item per recipient | Up to 100 items per request. |
| `attachment`, `inline` (multipart files) | `attachments: [{ filename, content (base64) }]` | Inline (`cid:`) images are not supported; host images on a URL. |
| `o:dkim`, `o:require-tls`, `o:skip-verification` | none | Signing and TLS are handled by the provider that carries the email. |

```bash
# before
curl -s --user "api:$MAILGUN_API_KEY" https://api.mailgun.net/v3/mg.acme.dev/messages \
  -F from='Acme <hello@mg.acme.dev>' -F to=ada@example.com -F subject=Hello -F text='Hi' -F o:tag=welcome

# after
curl -s -X POST "$ONESEND_BASE_URL/v1/emails" -H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
  -d '{"from":"Acme <hello@mg.acme.dev>","to":"ada@example.com","subject":"Hello","text":"Hi","tags":["welcome"]}'
```

If your app sends through Mailgun's SMTP relay, point it at OneSend's SMTP ingress instead (see [Gmail SMTP](https://onesend.email/docs/migrate/gmail-smtp/#smtp-settings) for the settings); `X-Mailgun-Tag` becomes `X-OneSend-Tags`.

## Other APIs

| Mailgun | OneSend |
|---|---|
| Events and logs API | `GET /v1/emails`, `GET /v1/emails/{id}` (attempts and events), `GET /v1/events` |
| Webhooks | OneSend webhooks ([Webhooks](https://onesend.email/docs/webhooks/)). OneSend registers its own webhook with Mailgun to receive delivery events. |
| Mailing lists | Contacts and lists (`/v1/contacts`, `/v1/lists`) with campaigns |
| Routes (inbound) | Inbox and mailboxes, receiving through Cloudflare Email Routing or the built-in receiver |
| Email validation | `POST /v1/tools/address` (syntax, MX, disposable and role addresses, suppressions; no mailbox probing) |

## DNS

Keep Mailgun's records on your sending domain (DKIM such as `smtp._domainkey` or `pic._domainkey`, SPF `include:mailgun.org` on the Mailgun domain, the `email.` tracking CNAME). If the Mailgun domain is a subdomain such as `mg.acme.dev`, keep sending from it, or add the root domain in OneSend to register it with all providers. Add the `_onesend-verify` TXT record. If you also move inbound mail, change the MX records last, after mailboxes are set up in OneSend.

## Suppressions

Export bounces, complaints and unsubscribes from Mailgun (the Suppressions pages or API, per domain) and import them as described in the [cutover checklist](https://onesend.email/docs/migrate/#general-cutover-checklist). Tag-scoped unsubscribes map best to `"scope":"broadcast"`.

Then follow the [general cutover checklist](https://onesend.email/docs/migrate/#general-cutover-checklist).
