Moving from Mailgun to Pharos

The order the work happens in.

1. 01

   Export the suppression list

   Pull every suppressed address out of Mailgun before anything else changes.

2. 02

   Verify the domain on Pharos

   Add four DNS records alongside the ones already there. Both providers stay authenticated.

3. 03

   Move the send call

   Point the application at POST /v1/send or the SMTP relay, behind whatever flag you use.

4. 04

   Ramp the traffic

   Move a share of sending across, watch the events, increase it. No cutover window is required.

5. 05

   Repoint the webhook and clean up DNS

   Move the event consumer, then remove the Mailgun records once nothing depends on them.

Steps two and three are reversible and can overlap for as long as you like. An SPF record may name both providers, DKIM selectors are independent of one another, and the single DMARC record does not change at any point. That is what makes a phased migration possible: there is no moment where the domain is authenticated for the new provider and not the old one.

Step 1 — export the suppression list.

Three lists — bounces, unsubscribes and complaints — and they are per sending domain rather than per account. An account sending from three domains has nine exports. There is also an allowlist, which is worth reading before you import anything: an address on it was deliberately exempted from suppression, and importing it as suppressed silently reverses a decision someone made on purpose.

# three lists, per domain, paginated
for domain in mg.yourdomain.com mg.otherdomain.com; do
  for list in bounces unsubscribes complaints; do
    curl -s -u "api:$MAILGUN_API_KEY" \
      "https://api.mailgun.net/v3/$domain/$list?limit=1000" \
      | jq -r --arg l "$list" '.items[] | [.address, $l] | @csv' \
      >> suppressions.csv
  done
done

# check the allowlist before importing anything
curl -s -u "api:$MAILGUN_API_KEY" \
  "https://api.mailgun.net/v3/mg.yourdomain.com/whitelists?limit=1000" | jq -r '.items[].value'

Paginate past the first page with the paging.next URL each response carries. A domain with more than a thousand bounces is normal, and a truncated export is the kind of error that only shows up as a complaint rate three weeks later.

Pharos suppresses an address automatically on a hard bounce and on a complaint, keeps the list per account, and lets you export it again whenever you like — including on the way out, if this page ever needs writing in the other direction. The difference between a hard and a soft bounce decides which addresses end up on it.

Steps 3 and 4 — move the call, then the traffic.

The send call is plain HTTP. There is no SDK to install and nothing to import, which means the change in your application is a URL, a header and a body shape rather than a dependency.

curl -X POST https://api.pharos.email/v1/send \
  -H "Authorization: Bearer $PHAROS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4471" \
  -d '{
    "from": "receipts@yourdomain.com",
    "to": "customer@example.com",
    "subject": "Your receipt",
    "html": "<p>Thanks for your order.</p>"
  }'

If you would rather not touch application code at all, point your existing mailer at the SMTP relay on smtp.pharosinfra.net:587 with STARTTLS. Same pipeline, same events, and a migration that is four lines of configuration. The Idempotency-Key header matters more during a migration than at any other time: a retry across a half-switched deployment is exactly the situation that sends a password reset twice.

Then ramp. Send a percentage, read the events, raise it. There is no warmup requirement to satisfy here — the sending IPs are dedicated to Pharos and already have a reputation — but ramping is still how you find the template that renders wrong or the address list nobody had cleaned, at a volume where finding it is cheap.

When to stay on Mailgun.

Four reasons not to do any of the above. They are here because you would find them during the migration otherwise, and finding them then costs a great deal more than reading them now.

• You use Routes for inbound mail

  Forwarding, storing and posting inbound mail to your application is a Mailgun feature with no Pharos equivalent. This is the single most common reason a Mailgun migration should be partial rather than total.

• You use mailing lists

  Mailgun’s mailing lists send one message to a stored group of members. Pharos carries transactional mail only and has nothing that stores a list of recipients for you.

• You use their email validation

  Address validation as a service is a separate product line there and does not exist here. If it is wired into your signup flow, it needs its own answer before the sending migration matters.

• You are on a dynamic IP pool at high volume

  If your sending is large enough that pool assignment is something you actively manage, you are operating at a scale where the honest conversation happens before the migration rather than during it.

Pharos carries transactional mail only — mail a recipient's own action caused. That single constraint is the reason for most of the gaps above, and it is written down in the acceptable use policy rather than discovered at suspension time.