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.
Is the domain ours?
The domain part is matched against the
[domains."…"]blocks, case-insensitively. No match means550 5.7.1: mxhop is not an open relay and will not carry mail for a domain it was not configured for.Is there a literal alias?
The local part is matched against the alias names, case-insensitively —
Hi,hiandHIare the same alias, as receivers expect. A match resolves immediately.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 arejectfor one specific address.Otherwise, no.
550 5.1.1 no such address here, atRCPTtime. 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 delivered | 250 2.0.0 delivered as <id> — the rest are queued or dropped, and either way mxhop has taken responsibility for them |
| none delivered, some deferred | The deferral is passed up as a 4xx, preferring the destination's own words over mxhop's |
| all refused for good | The 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.
- Prefer listing what exists. Five aliases you wrote down beat one wildcard, and an address that does not exist gets refused at
RCPTbefore any body is transmitted. - If you want per-service addresses, add them as you use them. The administrative cost is one line per signup; the spam saved is everything addressed to a guess.
- A catch-all plus a reject is a useful pair: the wildcard takes everything, and a literal
rejectfor a leaked address shuts off just that one, because a literal alias always wins.
[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.
| Limit | Value | What it stops |
|---|---|---|
| alias expansion depth | 8 | An 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 message | 100 | 452 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: headers | 25 | 554 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 host | 3 | 554 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 length | 200 | Longer 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.