30. pepsi-stage-bounce

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

30.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). References: pepsi-stage-bounce(1) / pepsi.conf(5).

30.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, and the body quotes the original headers; RFC 3463 enhanced status codes are used.

  • 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.

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

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

30.3. 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>) and NEXT_STAGE (required; normally a DKIM-sign stage). See pepsi.conf(5).

30.4. State

  • Inputs: state.bounce — kind, diagnostic, failed_recipient, and the copied notify/orcpt/envid (a hand-staged message with no state.bounce yields a generic failure notice).

  • Outputs: clears state to null — the bounce is a new null-sender message that inherits none of the original’s provenance. This is the only stage that does not preserve state.

30.5. See also

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