Migrating from Mailgun

The request shape is the same

Mailgun's HTTP send takes form fields from, to, subject, text and html. Ours is POST /emails with the same names in JSON. The full shape is on the POST /emails page.

Headers

headers takes a map of name to value. From, To, Subject, Message-ID and Date are refused in headers.

Error names resolve

Mailgun error names are not aliases here. Branch on our code. Every refusal carries message, fix and docs_url. The catalogue is at /docs/errors.

Payload map

Fetched from Mailgun's HTTP send page on 2026-09-28 (https://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/send-http).

Webhook events

Their securing-webhooks page, fetched 2026-09-28, describes an HMAC-SHA256 signature over timestamp and token. It does not list event names. Each of our types is listed so the gap is visible.

What will refuse on day one

• Inbound mail is not offered. A migration that depends on receiving mail at your domain does not have that path here.
• Keeping customer data in the EU is not offered. Data is processed in the United States.
• There is no business associate agreement for health data.
• A key is created with a send budget. A key that sends past the budget is refused with agent_budget_exceeded rather than invoiced.

The compatibility client, when the import line is all you want to change

That client mirrors one provider's SDK (agentisend/compat-resend). It does not mirror this provider. Call POST /emails with from, to, subject, html and text.

Contacts

POST /contacts accepts first_name, last_name, unsubscribed and properties. unsubscribed: true records that the person asked not to receive marketing mail. GET, PATCH and DELETE /contacts/{id} take the contact id or the email address. The Mailgun pages fetched on 2026-09-28 cover pricing, webhook signing and the HTTP send. They do not document a contact-import field map, so this guide does not invent one. Add each person with POST /contacts. An API key cannot lift an unsubscribe.

The bounce return path

A domain that already sends from somewhere else often has an MX record on send. Creating it here without a return-path label then uses bounce instead of refusing the domain. To choose the label, pass custom_return_path on POST /domains.

Two differences, both deliberate

Keys have budgets, and the budget is enforced. Set the budget to your real volume before you cut over.

Inbound mail and an EU data region are not part of the move. If the old account uses either, that part stays on the old provider.

What you gain in the move

• Per-key budgets and one kill switch for the account, on Budgets and the kill switch.
• An approval queue for a send the loop guard flags, or one an agent asks about with request_approval, on Approvals.
• Signed webhooks, a replay call, and a dead-letter list, on Webhooks.

Order of operations

1. Add and verify your domains here while the old provider still sends.
2. Create keys with budgets, one per sender, and point webhooks at the new signing scheme.
3. Move a low-volume stream first.
4. Move the rest, and keep the old keys alive until you have a week of clean data.