mxhop

Reference · routing

An address in, a list of mailboxes out.

Routing is pure: the same address and the same alias table always give the same answer, with no network and no clock involved. That is why mxhop check can prove things about it before any mail arrives.

Resolution order

A recipient is resolved at RCPT TO time, before the sender transmits a single byte of the body. The steps run in this order and stop at the first that answers.

  1. Is the domain ours?

    The domain part is matched against the [domains."…"] blocks, case-insensitively. No match means 550 5.7.1: mxhop is not an open relay and will not carry mail for a domain it was not configured for.

  2. Is there a literal alias?

    The local part is matched against the alias names, case-insensitively — Hi, hi and HI are the same alias, as receivers expect. A match resolves immediately.

  3. Is there a catch-all?

    Only now is "*" considered. A literal alias always wins over the catch-all, which is what lets you have a catch-all and a reject for one specific address.

  4. Otherwise, no.

    550 5.1.1 no such address here, at RCPT time. The sender learns straight away and never transmits the body.

The four target forms

[domains."example.com".aliases]

# 1. one recipient
hi = "you@gmail.com"

# 2. several. each gets its own attempt and its own fate
team = ["you@gmail.com", "colleague@fastmail.com"]

# 3. a named host, skipping the MX lookup
legacy = { to = "old@internal.example", via = "mail.internal.example" }

# 4. refuse, in your own words, at RCPT time
noreply = { reject = "550 5.1.1 this address does not accept mail" }

# and the catch-all, which may be any of the four
"*" = "you@gmail.com"

A list is not a copy of one message

Each address in a list is tracked separately. If Gmail takes its copy and Fastmail defers, the sender gets 250 — the message was delivered to somebody — and only the Fastmail copy is queued for retry. The reply the sender sees is the best outcome among the recipients, not the worst:

at least one delivered250 2.0.0 delivered as <id> — the rest are queued or dropped, and either way mxhop has taken responsibility for them
none delivered, some deferredThe deferral is passed up as a 4xx, preferring the destination's own words over mxhop's
all refused for goodThe refusal is passed up as a 5xx, again preferring what the destination actually said

via: when DNS is not the answer

via connects to a named host directly instead of looking up the recipient domain's MX. It is for an internal mail host, a machine on a VPN, or a destination whose MX you deliberately do not want to follow.

mxhop check resolves every via host and fails if one has no address. The reasoning is that 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.

/etc/mxhop/mxhop.toml:22: via = "mail.internal.example" has no address, so mail for legacy would have nowhere to go and nothing in DNS would say so

reject: your words, verbatim

The string is sent as-is, so it must be a valid SMTP reply: a three-digit code, optionally an enhanced status code, then text. Refusal happens at RCPT TO, which matters — the sender is told immediately, nothing is queued, and no bounce is ever generated in your name.

RCPT TO:<noreply@example.com>
550 5.1.1 this address does not accept mail

Use 5xx for "never"; a 4xx here tells senders to keep trying forever, which is rarely what anyone means.

The catch-all, honestly

A catch-all is convenient and it is also a spam magnet. Every possible address at your domain becomes real, so a dictionary attack has a one hundred percent hit rate and all of it lands in the mailbox you actually read.

[domains."example.com".aliases]
"*" = "you@gmail.com"
leaked-2019 = { reject = "550 5.1.1 this address was retired" }

Loops and limits

Every bound here exists because the unbounded version is either an amplifier somebody else pays for or a way to make this host part of a mail loop.

LimitValueWhat it stops
alias expansion depth8An alias pointing at another address at one of your own domains is expanded again. Eight levels deep, and a cycle is caught outright: 550 5.4.6 the alias for … points in a circle. check finds these before any mail arrives, with the line number.
recipients per message100452 4.5.3 too many recipients for one message. Temporary on purpose: the sender should send the rest in another message rather than give up.
Received: headers25554 5.4.6 too many hops. A message that has already been through twenty-five hops is going round in a circle somewhere.
passes through this host3554 5.4.6 this message has already passed through this host. Counted from mxhop's own traces, so a loop that includes you is cut even when the total hop count is low.
Message-ID length200Longer is truncated for logging. It is the one header value that appears in a log line, so it is bounded.

Duplicate targets are collapsed. If team lists an address twice, or two aliases in one message resolve to the same mailbox, that mailbox gets one copy — not one per path that reached it.

How recipients become deliveries

After expansion, targets are grouped by destination domain and via host. Each group is one SMTP conversation with one server, carrying every recipient in it.

# one message to three aliases
RCPT TO:<hi@example.com>      → you@gmail.com
RCPT TO:<team@example.com>    → you@gmail.com, colleague@fastmail.com
RCPT TO:<legacy@example.com>  → old@internal.example via mail.internal.example

# becomes two connections, not four
gmail.com          → you@gmail.com                 (deduplicated)
fastmail.com       → colleague@fastmail.com
mail.internal...   → old@internal.example          (via, its own group)

Each group gets its own time budget of five minutes. A destination that is slow delays only its own group; the others are not waiting on it.