Migrate from Mailgun

Mailgun sends form-encoded requests with prefixed option fields (o:, h:, v:); Mailhuset takes one JSON body with plain field names. The concepts map closely, so plan for an afternoon, most of it waiting on DNS.

1. Verify your sending domain

Add your domain under Domains and publish the SPF, DKIM and DMARC records, as you did for Mailgun. See Verify a sending domain. Leave Mailgun's records in place until you have cut over, so both can send in parallel.

Sending through Mailgun's SMTP service rather than its API? Then you can skip step 2: point your app's SMTP settings at smtp.mailhuset.com (port 587 with STARTTLS) with an SMTP credential, and no code changes. SMTP is included on paid plans.

2. Swap the API call

A Mailgun call like this:

curl -s --user "api:$MAILGUN_API_KEY" \
  https://api.eu.mailgun.net/v3/yourdomain.com/messages \
  -F from="Acme <hello@yourdomain.com>" \
  -F to=a@example.com \
  -F subject="Your receipt" \
  -F html="<p>Thanks for your order</p>"

becomes:

curl -s https://api.mailhuset.com/v1/email \
  -H "Authorization: Bearer $MAILHUSET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "Acme <hello@yourdomain.com>", "to": ["a@example.com"],
        "subject": "Your receipt", "html": "<p>Thanks for your order</p>" }'

The sending domain comes from the from address, not the URL. To send many messages in one call, use POST /v1/email/batch (up to 500). See Send email via the API, or use an official SDK.

3. Recreate templates

Re-create your Mailgun templates under Templates with an alias, and pass the variables you sent in h:X-Mailgun-Variables as templateModel. Plain fields carry over as they are: {{ first_name }}, dotted paths like {{ order.total }}, and {{{ raw_html }}} for unescaped HTML.

Mailhuset templates have no {{#if}} or {{#each}} blocks. Where a Mailgun template loops or branches, build that part in your code and pass it in as one field, or send the finished html directly. See Templates.

4. Bring your suppressions with you

Export Mailgun's bounces, complaints and unsubscribes for your domain, then import them so Mailhuset never mails an address Mailgun already learned to avoid:

POST https://api.mailhuset.com/v1/suppressions/import
Authorization: Bearer $MAILHUSET_API_KEY

{ "entries": [
  { "address": "old@example.com", "reason": "HARD_BOUNCE" },
  { "address": "angry@example.com", "reason": "COMPLAINT" },
  { "address": "optout@example.com", "reason": "UNSUBSCRIBE" }
] }

Up to 20,000 entries per call. Bad rows are skipped and counted, never fatal. See Suppressions.

5. Point webhooks at Mailhuset

Add your endpoint under Webhooks and map Mailgun's events:

Mailgun's accepted corresponds to Mailhuset accepting your API call, and a temporary failed has no event because Mailhuset retries for you. Every Mailhuset event is signed, so verify it with your endpoint's signing secret. See Webhooks.

6. Move inbound routes

If you receive mail through Mailgun Routes, recreate them under Inbound: Mailhuset parses each message to JSON and posts it to your webhook. See Inbound email.

7. Cut over

Send a share of traffic through Mailhuset first, watch delivery and events in Activity, then move the rest over a few days rather than in one spike.

Questions during migration? Email support@mailhuset.com.

Need help? Email support@mailhuset.com.