mxhop

Guides · scenarios

Seven setups, with the whole config each time.

Every config below is complete — copy it, change the names, run mxhop check. Each one also says what it costs you, because every one of these trades something.

1. One personal domain

the common case · one domain, a handful of addresses, one mailbox you read

You own example.com, you read mail in Gmail, and you want hi@, bills@ and git@ to land there without Google knowing the domain exists.

hostname = "mx.example.com"
listen = "0.0.0.0:25"
spool_dir = "/var/lib/mxhop/spool"

[domains."example.com".aliases]
hi = "you@gmail.com"
bills = "you@gmail.com"
git = "you@gmail.com"
noreply = { reject = "550 5.1.1 this address does not accept mail" }

[tls]
certificate = "/etc/letsencrypt/live/mx.example.com/fullchain.pem"
key = "/etc/letsencrypt/live/mx.example.com/privkey.pem"

[srs]
domain = "example.com"
secret_file = "/etc/mxhop/srs.key"

[auth]
enabled = true
enforce = "dmarc"

[observe]
listen = "127.0.0.1:9779"

Add [arc] once this works. It is the one block worth adding later rather than up front — it needs a key and a DNS record, and nothing else depends on it.

Separate aliases per service, rather than a catch-all, means you can see which one leaked and shut just that one off.

2. Several domains, one host

one machine, several identities, different mailboxes

One block per domain. The hostname stays the same for all of them — it names the machine, not the domains.

hostname = "mx.example.com"
listen = "0.0.0.0:25"
spool_dir = "/var/lib/mxhop/spool"

[domains."example.com".aliases]
hi = "you@gmail.com"

[domains."example.net".aliases]
hello = "you@gmail.com"
support = ["you@gmail.com", "colleague@fastmail.com"]

[domains."side-project.dev".aliases]
"*" = "projects@fastmail.com"

[srs]
domain = "example.com"
secret_file = "/etc/mxhop/srs.key"

One SRS domain serves all of them, and that is fine — it only needs to be a domain whose SPF authorises this host and whose MX points here, because that is where bounces come back to.

But each domain needs its own MX, SPF and DMARC records. The A and PTR are shared, since there is one machine. See DNS for several domains.

3. A shared address for a few people

two or three people, one address, no mailing list software

A list target fans one message out to several mailboxes, each tracked separately. If one defers, the others still get theirs.

[domains."example.com".aliases]
support = ["ann@gmail.com", "ben@fastmail.com", "cat@proton.me"]
founders = ["ann@gmail.com", "ben@fastmail.com"]
ann = "ann@gmail.com"
ben = "ben@fastmail.com"

This is fan-out, not a mailing list. Replies go wherever the recipient's mail client sends them — normally to the original sender, not back to the group — and there is no archive, no subscription, no List-Id header. Three people sharing an inbox is the ceiling of what this is good for.

Above that, you want real list software behind a via alias, or a shared mailbox at your provider.

4. Moving off a hosted forwarder

ImprovMX, Cloudflare Email Routing, a registrar's forwarding — without losing mail in the gap

The trick is to run both at once. A second MX at a higher preference number is a fallback, so there is never a moment when nothing is listening.

  1. Build the mxhop host and prove it

    Everything except the MX record. Test it on a high port with a real message, and run mxhop check.

  2. Add mxhop as the lower-priority MX

    example.com.  MX  10 mx.improvmx.com.   <- still primary
    example.com.  MX  20 mx.example.com.    <- yours, as fallback

    Senders prefer 10. You will see occasional mail arrive at yours when the primary is briefly busy, which is exactly the live test you want.

  3. Swap the numbers

    example.com.  MX  10 mx.example.com.    <- yours, now primary
    example.com.  MX  20 mx.improvmx.com.   <- old one, as fallback

    Now your host takes everything, and the old service catches anything that arrives while yours is restarting.

  4. Wait a day, then remove the old record

    Watch mxhop_messages_accepted_total climb and the old service's dashboard go quiet. Only then drop the 20 record and cancel the account.

Update SPF before step 3, not after. Your host starts sending as soon as it is primary, and if SPF does not authorise it yet, every forwarded message fails at the destination. Add this host to the existing record rather than replacing it, while both are in play.

5. An internal host behind the public MX

a legacy mail server, a ticketing system, something on a VPN

via hands mail to a named host instead of following the recipient domain's MX. Useful when the destination is not reachable from public DNS, or when you deliberately do not want to follow what DNS says.

[domains."example.com".aliases]
hi = "you@gmail.com"
tickets = { to = "intake@helpdesk.internal", via = "helpdesk.internal" }
legacy = { to = "archive@old.internal", via = "10.0.0.14" }

mxhop check resolves every via host and fails if one has no address. That check exists because a via pointing at a name that does not resolve is mail with nowhere to go, and unlike a bad MX record, nothing in public DNS would ever tell you.

An IP literal works and skips resolution entirely. Mail to a via host is still delivered over SMTP with STARTTLS if the host offers it; via changes where to connect, not how.

6. A staging MX you can experiment on

trying a config change without risking real mail

Use a domain nobody writes to, a high port, and a spool of its own. Nothing here touches your production install.

hostname = "mx-staging.example.com"
listen = "0.0.0.0:2525"
spool_dir = "/var/lib/mxhop-staging/spool"

[domains."staging.example.com".aliases]
"*" = "you+staging@gmail.com"

[auth]
enabled = true
enforce = "off"        # stamp verdicts, refuse nothing

[queue]
retry_minutes = [1, 2]
lifetime_hours = 1     # fail fast instead of sitting for two days

[observe]
listen = "127.0.0.1:9780"

Send into it with the hidden send-test, or by hand:

mxhop --config /etc/mxhop/staging.toml send-test you+staging@gmail.com "does this arrive"
delivering to you+staging@gmail.com as mx-staging.example.com over port 25
gmail-smtp-in.l.google.com answered:
  you+staging@gmail.com: accepted

accepted means Gmail's servers took it, not that it reached the inbox. A message can be accepted and filed as spam. Check the mailbox itself, and read the Authentication-Results header in "Show original" — that is where you find out whether SPF, DKIM, DMARC and ARC actually passed.

7. Two hosts, so a reboot is not an outage

when a few minutes of deferred mail is not acceptable

Two MX records at equal preference. Senders pick either; both forward to the same mailboxes. There is nothing to synchronise, because mxhop holds no shared state — each host has its own spool for whatever it accepted.

example.com.  MX  10 mx1.example.com.
example.com.  MX  10 mx2.example.com.

example.com.  TXT "v=spf1 a:mx1.example.com a:mx2.example.com -all"

Identical configs except hostname. Each needs its own A and its own PTR.

Honestly, you probably do not need this. SMTP already retries for days — a sender whose message is deferred by a reboot delivers it minutes later, and nobody notices. A second host doubles what you patch and monitor, to remove a delay senders already tolerate by design.

Worth it if you forward something time-sensitive, like password resets or alerts. Not worth it for personal mail.