63. pepsi-stage-route

Send each recipient to the next hop their domain selects.

63.1. Role

pepsi-stage-route makes the one routing decision that a gateway in front of another mail system must make for every inbound message: does this recipient belong to the system behind me, or to the internet? It picks a next stage per envelope recipient from that recipient’s domain, splitting the message when recipients disagree. It only moves the stage column: it never rewrites, delivers, bounces or drops a message, and state (including state.dsn) is preserved. Reference: pepsi-stage-route(1).

Getting that decision wrong is not a delivery failure but a mail loop: the domains behind the gateway are exactly the domains whose public MX is the gateway. See Microsoft Exchange as a gateway for the deployment this stage exists for.

63.2. Features

  • Managed domains by default. MANAGED_DOMAINS defaults to [pepsi-ingress] ACCEPTED_DOMAINS, so the set of domains treated as “behind the gateway” cannot drift from the set ingress actually accepts. With MANAGED_STAGE set, the whole gateway topology is two options.

  • Explicit rules for carve-outs. ROUTES takes whitespace- or comma-separated <domain>=<stage> pairs, consulted before the managed set, so one subdomain can go elsewhere without removing its parent from MANAGED_DOMAINS (which would also stop ingress accepting it).

  • Glob patterns, not regexes. * matches any run of characters and the match is anchored at both ends: *.example.org matches mail.example.org but not example.org nor mail.example.org.evil.test. A pattern that looks like a regular expression is rejected at configuration time rather than silently matching nothing.

  • Per-group recipient fan-out. Divergent recipients become sibling pending rows in one database call, each carrying only its own recipients with state.dsn.rcpt sliced to match rcpt_to.

  • Deterministic grouping. Groups are formed in first-seen order, so a retried message keeps the same recipients on the same row.

  • Metadata only. Neither the headers nor the body is loaded.

Note

Unlike the other metadata-only stages, this one does not default to FUSION = yes. On paper it is a candidate, since it is folded into the unified binary and loads no message content. But a fused stage runs inside its predecessor’s worker, and this stage’s recipient fan-out refuses to run with a predecessor’s uncommitted content changes pending. Rather than make that interaction a run-time surprise, the stage is simply dispatched normally.

63.3. Loop prevention

pepsi-setup does not just warn about two configurations; it refuses them:

  • one in which a message for a served domain could reach pepsi-stage-relay-to-internet. pepsi-setup finds it by walking forward from every stage that a managed recipient can reach, along every option that sends the message itself on: NEXT_STAGE, route targets, pepsi-stage-if’s TRUE_STAGE and FALSE_STAGE, a milter’s ACCEPT_STAGE/QUARANTINE_STAGE, decrypt’s QUARANTINE_STAGE, encrypt’s SECURE_LINK_STAGE, the secretary’s UNCHALLENGEABLE_STAGE and the paywall’s BOUNCE_TARGET_STAGE. BOUNCE_STAGE and the other failure routes (a milter’s REJECT_STAGE, the local-delivery stages’ quota, Sieve, notification and unknown-mailbox targets) are not followed: what travels there becomes a null-sender DSN about a delivery that already failed, and it legitimately reaches a relay. Nor are RESPONSE_STAGE-style targets (a new message to somebody else), a ~/.forward RESTART_STAGE or the mailing-list stages’ targets, which re-address the message to new recipients.

  • a [pepsi-stage-relay-to-smarthost-mta-*] section whose HOST is this host and whose PORT is one that an ingress listener is bound to. Both halves are required, because a site may legitimately run an unrelated relay on the same host, or reach a different machine on port 25.

They are refusals because a loop only stops when the relay stages’ MAX_HOP_COUNT guard fires, tens of copies later, and the bounce that guard then produces is itself addressed back into the loop. The hop-count guard and the other loop breakers are listed under “Loops and amplification” in Availability.

63.4. Configuration

Option

Meaning

ROUTES

Whitespace/comma separated <domain-pattern>=<stage> pairs, consulted first, in order. Optional.

MANAGED_DOMAINS

The domains behind this gateway. Defaults to [pepsi-ingress] ACCEPTED_DOMAINS; at least one is required.

MANAGED_STAGE

Where a recipient at a managed domain goes. Optional; without it managed recipients take NEXT_STAGE, which pepsi-setup then has to prove is not a loop.

NEXT_STAGE

Where every other recipient goes. Required — the stage never delivers, bounces or drops, so every recipient must have somewhere to be.

RECIPIENT_CHECK

none (default), probe or map: how pepsi-ingress asks whether an address at a managed domain exists, so an unknown one is refused at RCPT. probe asks PROBE_HOST (PROBE_PORT default 25, PROBE_TLS opportunistic/starttls/tls/none, PROBE_TIMEOUT default 10 s); map reads RECIPIENT_MAP. Read by ingress only, not by the stage. With none, ingress refuses % and ! in a managed local part (550 5.1.3); disable the percent hack and bang paths in the backend as well (Postfix allow_percent_hack = no, swap_bangpath = no).

63.5. Placement

Place the stage on the inbound path, after authentication and decryption and before the relay stages. A typical order is arc → decrypt → aliases → route, with MANAGED_STAGE naming the smarthost stage that relays to Exchange and NEXT_STAGE naming the direct-to-MX stage.

63.6. See also