Migrate from Mailgun to Unitpost

Before you start

• Your account Private API key (Settings → API Security). A domain sending key cannot read lists or suppressions.
• If you have EU domains: Mailgun API keys are account-wide, and the importer keeps the US API whenever the key works there. EU lists and suppressions live only in the EU region, so plan to check them by hand (step 2).
• A Unitpost API key with emails:send for your app, created in API keys.
• A second Unitpost key for the migration steps, with domains:write, suppressions:write, templates:write and webhooks:manage, saved as UNITPOST_MIGRATION_KEY. Keep it out of your app and revoke it once the move is done.
• Access to your DNS host, including the MX records if Mailgun receives mail for you.

The cut-over plan

Mailgun keeps sending until the last step, so there is no gap in delivery.

1. 1

   Run the Migration Assistant

   Paste the key in Settings → Migration. The account label in the preview names the region it read (Mailgun US or Mailgun EU). Suppressions are written before contacts, so unsubscribed members land unsubscribed.

2. 2

   Bring EU suppressions over by hand if needed

   If the preview says US and you also send from EU domains, read each EU domain's /v3/{domain}/bounces, /complaints and /unsubscribes on api.eu.mailgun.net and add the addresses with POST /api/v1/suppressions (emails, up to 1,000 per call) before the first send.

3. 3

   Verify your domains next to Mailgun

   Open Domains and publish the records shown: MX and SPF on unitpost.<your domain> and a DKIM TXT under _domainkey. Mailgun's records keep working, so the domain is verified on both. Keep your single _dmarc record.

4. 4

   Rebuild routes as receiving

   If Mailgun receives for a domain, its MX points at mxa.mailgun.org and mxb.mailgun.org (EU: mxa.eu.mailgun.org, mxb.eu.mailgun.org). Turn receiving on with PATCH /api/v1/email/domains/{id} (capabilities.receiving set to enabled), subscribe an endpoint to email.received, then swap the MX record.

5. 5

   Port templates

   Mailgun templates use Handlebars with if, unless, each, with and equal. Unitpost fills {{name}} placeholders only, so render those blocks in code, and replace %unsubscribe_url% with {{unsubscribe_url}}. Set receipts to transactional (imports land as marketing, which adds a footer) and publish with PATCH /api/v1/email/templates/{id}.

6. 6

   Switch to JSON and a Bearer key

   The domain leaves the path, form fields become JSON, o:tag becomes tags, template with t:variables becomes template: { id, variables }, and o:deliverytime becomes ISO 8601 scheduled_at (up to 90 days ahead, against Mailgun's plan-dependent window of up to 7 days).

   send.ts

   // Before: Mailgun (form fields, HTTP Basic auth)
   const form = new FormData();
   form.append("from", "Acme <hi@mg.acme.com>");
   form.append("to", "user@example.com");
   form.append("subject", "Your receipt");
   form.append("html", receiptHtml);
   await fetch("https://api.mailgun.net/v3/mg.acme.com/messages", {
     method: "POST",
     headers: {
       Authorization: "Basic " + Buffer.from("api:" + process.env.MAILGUN_API_KEY).toString("base64"),
     },
     body: form,
   });
   
   // After: Unitpost (JSON, Bearer key, no domain in the path)
   import { Unitpost } from "unitpost";
   const unitpost = new Unitpost(process.env.UNITPOST_API_KEY);
   const { data, error } = await unitpost.email.send({
     from: "Acme <hi@mg.acme.com>",
     to: "user@example.com",
     subject: "Your receipt",
     html: receiptHtml,
   });

7. 7

   Replace the webhook verifier

   Mailgun signs timestamp and token in the body with one account-wide signing key. Unitpost signs the raw body with a per-endpoint whsec_ secret in the svix headers (svix-id, svix-timestamp, svix-signature). Rotate the secret in Webhooks to see it, deploy the verifier, then set status to enabled; a switched-off endpoint does not queue events.

8. 8

   Send tests

   Send each template with POST /api/v1/email/templates/{id}/test-send, mail a test message to a receiving domain, and fire POST /api/v1/webhooks/{id}/test at each endpoint.

9. 9

   Move traffic in stages

   Move one message type first, watch email.bounced and email.complained, then the rest. Mailgun stays verified, so rolling back is a config change.

10. 10

    Cancel Mailgun last

    Wait for messages scheduled at Mailgun to go out, finish the checks below, then close the account.

Before you cancel Mailgun

• Pull bounces, complaints and unsubscribes for every domain in both regions one last time and add new ones here.
• Export the logs and stats you want to keep; none of them move.
• Move MX records off mxa and mxb before routes stop working.
• Delete Mailgun's DKIM, SPF and tracking records once no mail goes through Mailgun. Keep _dmarc and Unitpost's records.
• Delete Mailgun webhooks at domain and account level, and its API keys and SMTP credentials.

Facts about Mailgun checked 2026-11-02. Providers change their APIs and plans; check their docs before you rely on a detail.