33. pepsi-stage-relay-to-smarthost

Relay through a configured upstream smarthost.

33.1. Role

pepsi-stage-relay-to-smarthost relays mail to a configured upstream MTA (smarthost) chosen by recipient domain, instead of contacting MX hosts directly. It is the other interchangeable delivery stage. Reference: pepsi-stage-relay-to-smarthost(1).

33.2. Features

33.2.1. Smarthost routing

  • Routes each recipient domain to the […-mta-<name>] whose DOMAINS lists it, or to the single CATCH_ALL MTA; a domain with no matching MTA is a permanent failure. The MTA sections are shared across all smarthost-relay stages.

  • No MX discovery and no DNS-learned MTA-STS — it speaks only to the configured smarthosts.

33.2.2. Transport and authentication

  • Per-MTA transport plain / tls (implicit) / starttls (RFC 3207).

  • Certificate verification against the system store (plus an optional extra TLS_CA), or disabled for testing.

  • SMTP AUTH (RFC 4954): AUTH PLAIN or AUTH LOGIN with per-MTA USERNAME/PASSWORD.

  • HELO_NAME per MTA (defaults to SERVER_NAME).

33.2.3. Delivery, retry and bounce

  • Sends with the message’s own envelope sender.

  • On success, finishes the row (or advances to NEXT_STAGE).

  • Exponential backoff on transient failure up to MAX_LIFETIME; loop detection via MAX_HOP_COUNT.

  • A permanent failure (including no matching MTA) routes to BOUNCE_STAGE (or marks failed); a permanent failure of a bounce is discarded, never re-bounced.

33.2.4. DSN and content adaptation

  • Propagates RET/ENVID/NOTIFY/ORCPT to the smarthost only when it advertises DSN (RFC 3461); originates failure/success/delay reports under the same rules as the direct stage.

  • Per-hop 8BITMIME/SMTPUTF8 re-advertising or downgrade (RFC 6152 / RFC 6531 / RFC 2045 / RFC 2047).

33.3. Configuration

[stage-<name>] with PROGRAM = pepsi-stage-relay-to-smarthost: SERVER_NAME (required), NEXT_STAGE/BOUNCE_STAGE, the timeouts, the retry policy (incl. DELAY_DSN_AFTER) and MAX_HOP_COUNT. The upstream MTAs are defined in shared [pepsi-stage-relay-to-smarthost-mta-<name>] sections: HOST/PORT (required), MODE, TLS_VERIFY/TLS_CA, AUTH with USERNAME/PASSWORD, HELO_NAME, and routing via DOMAINS / CATCH_ALL. Full reference: pepsi-stage-relay-to-smarthost(1).

33.4. State

Identical to pepsi-stage-relay-to-internet:

  • Inputs: state.dsn and state.origin.

  • Outputs: attempts/last_error/delay_sent on pause; a state.bounce object when routing to/enqueuing for the bounce stage; last_error on terminal fail. state.dsn/state.origin preserved.

33.5. See also

pepsi-stage-relay-to-internet, pepsi-stage-bounce, Supported Features, pepsi-stage-relay-to-smarthost(1).