40. pepsi-stage-bounce

Rewrite a message into a delivery-status notification (DSN).

40.1. Role

pepsi-stage-bounce turns a message into an RFC 3464 DSN: a failure bounce or, when requested, a positive or delay report. A delivery stage routes a failed/delivered message here via its BOUNCE_STAGE. The DSN is produced unsigned and advanced to NEXT_STAGE (normally pepsi-stage-dkim-sign, then a delivery stage) after a random hold of up to [pepsi] REFLECTION_HOLD_MAX (30 s), as every piece of reflected mail is (Unknown recipients and backscatter). References: pepsi-stage-bounce(1) / pepsi.conf(5).

40.2. Features

  • In-place rewrite into a DSN (RFC 3464 multipart/report): the envelope sender becomes the null sender <>, the recipient becomes the original sender (state.srs.original when pepsi-stage-srs recorded one, else the mail_from column), and the body quotes the original headers; RFC 3463 enhanced status codes are used.

  • RET=FULL (RFC 3461 §6.2): when the sender asked for the whole message back, the stage fetches the body and returns it in full. This is the one extra round-trip in the tree, made only for such a message. If the body exceeds RET_FULL_MAX_SIZE (default 256 KiB, 0 to disable the limit), the DSN falls back to the headers alone, as §6.2 explicitly permits.

  • Operator-supplied prose. When BOUNCE_MESSAGE names a template, the human-readable part of the DSN is rendered from bounce-<NAME>.<lang>.body under [pepsi] TEMPLATE_DIR with the full row state. <lang> follows state.language in q order, falling back to en: the notice goes to the original sender, and the language detected in their message is the best available proxy for what they read (with no detection on the path, the notice is English). Any render failure falls back to the built-in text, so a bounce is always produced.

  • NOTIFY-aware (RFC 3461): a failure report is emitted only when NOTIFY requested FAILURE (the default when absent); NOTIFY=NEVER (or a list without FAILURE) drops the message silently.

  • Three report kinds, selected by state.bounce.kind:

    • permanent → Action: failed (the default failure bounce);

    • success → Action: delivered (only when a delivery stage originated it under ORIGINATE_SUCCESS_DSN + NOTIFY=SUCCESS);

    • delay → Action: delayed (a relay stage’s DELAY_DSN_AFTER warning).

  • Echoes the original ENVID/ORCPT into Original-Envelope-Id / Original-Recipient when present.

  • Keeps forwarding addresses confidential: for a recipient that an alias or ~/.forward expansion produced (expanded_from), the DSN names the address that the sender used as Final-Recipient and gives a generic Diagnostic-Code of the same class (550 <status> delivery to a forwarded address failed) with the enhanced Status: kept; the target and the real reply go to the journal only (RFC 3464 §4.2). The same DSN answers a remote host’s report about a forwarded copy: pepsi-ingress turns a report sent to the copy’s forward return address into a row at this stage (state.forward_return) and drops the report (Forwarding addresses in delivery reports).

  • Nothing to quote, no third part: when a DSN has nothing of the message to quote, it is a two-part multipart/report (RFC 6522 §3). This is the case for the report about a forwarded copy of a message that arrived encrypted.

  • Never bounces a bounce (RFC 5321 §6.1): a null-sender message is deleted, not rewritten.

  • No backscatter (BOUNCE_UNAUTHENTICATED, default drop): no report goes to an envelope sender that the inbound message did not authenticate (SPF pass for its domain, or an aligned DKIM pass for a From: at that domain or a parent or subdomain of it). Mail that our own users submitted and messages that a stage created (no state.auth) are always reported; a dropped report about a failure on this host is logged as a warning.

  • Failures on this host (no state.bounce: a stage’s error outlived MAX_LIFETIME or was permanent, a worker crash, or pepsi-failure-bouncer): the row is split into one row per recipient, each recipient’s own state.dsn NOTIFY/ORCPT/RET is honoured, and the DSN carries a generic diagnostic chosen by state.failure_class (Status: 5.4.7, 5.3.0, 5.6.0, 5.7.1 or 5.0.0); state.last_error is never copied into it.

  • Content of mail that arrived encrypted is withheld: whatever RET asks, the DSN quotes only From/Sender/To/Cc/Date/ Message-ID, whether or not decryption succeeded, so the DSN can neither hand plaintext to whoever re-sent a captured ciphertext nor reveal whether it opened. Every quoted header block loses Pepsi’s X-Pepsi-* fields.

  • A ``REQUIRETLS`` message bounces headers-only (RFC 8689 §5 disregards RET=FULL), and the DSN inherits the state.tls_required tag so the relay stages return it only over validated TLS.

  • No network I/O: the rewritten message is delivered by whatever NEXT_STAGE names; the bounce is left unsigned for the DKIM-sign stage.

40.3. Security

Two of the features above are security mechanisms. The backscatter rule is the second layer of “Unknown recipients and backscatter” in Security model (protecting the host’s sending reputation, Assets, against A remote sender). Withholding the content of mail that arrived encrypted is “Bounces and replies to encrypted mail” there: it keeps plaintext that the gateway opened from reaching whoever the envelope sender is, and keeps the DSN from being a decryption oracle (Gateway custody (custody = local, the MTA key), Bounces after gateway decryption reveal decrypted content, CBC padding and format oracles against unauthenticated S/MIME). The diagnostic of a failure on this host never quotes state.last_error, which can name files, database objects and hosts. That a bounce is never bounced is part of the loop analysis in Availability.

40.4. Configuration

[stage-<name>]: PROGRAM = pepsi-stage-bounce, SERVER_NAME (required; used in ``From:``/``Reporting-MTA``/``Message-ID``), POSTMASTER (the bounce From: and DKIM identity; default postmaster@<SERVER_NAME>), BOUNCE_MESSAGE (the template name, unset for the built-in prose), RET_FULL_MAX_SIZE (default 256 KiB), BOUNCE_UNAUTHENTICATED (drop/send, default drop) and NEXT_STAGE (required; normally a DKIM-sign stage: the DSN is built unsigned, so without one every bounce fails after the DSN has already been composed). See pepsi.conf(5).

40.5. State

  • Inputs: state.srs.original (the DSN recipient, when present) and state.bounce with kind, diagnostic, failed_recipient, the structured next-hop detail that the relay stages record (remote_mta/smtp_code/enhanced_status/phase/reply_text, which also feeds the DSN Status:), and the copied notify/orcpt/envid/ret. Without state.bounce the report is built from state.failed_stage/state.failure_class and the recipient’s state.dsn entry. state.auth/state.local_origin vet the DSN recipient, state.crypto.in decides whether content is withheld and state.language picks the template language; state.tls_required (RFC 8689) forces the headers-only form and is carried onto the DSN. A report spawned as a separate row beside the original (a per-recipient bounce or success notice, a delay warning) carries the original’s state under its own bounce record, so the same checks apply to it. The header block is loaded; the body is loaded only for a RET=FULL bounce.

  • Outputs: replaces state with {"retry_since": <now>}, because the bounce is a new null-sender message that inherits none of the original’s provenance, and the later stages count its MAX_LIFETIME from when it was built. This is the only stage that discards the state that it receives. The other stages keep it and add keys of their own; a stage that changes the recipients also rebuilds the state.dsn entries to match.

40.6. See also

pepsi-stage-dkim-sign, pepsi-stage-relay-to-internet, pepsi-stage-discard, pepsi-failure-bouncer, Supported Features, pepsi-stage-bounce(1), pepsi.conf(5).