..
  This file is part of PEPSI.
  Copyright (C) 2026 Pepsi contributors

  PEPSI is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free
  Software Foundation; either version 3, or (at your option) any later version.

==================
pepsi-stage-bounce
==================

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

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 :doc:`pepsi-stage-dkim-sign`,
then a delivery stage). References: :manpage:`pepsi-stage-bounce(1)` /
:manpage:`pepsi.conf(5)`.

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.

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
:manpage:`pepsi.conf(5)`.

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

See also
========

:doc:`pepsi-stage-dkim-sign`, :doc:`pepsi-stage-relay-to-internet`,
:doc:`pepsi-stage-discard`, :doc:`../features`, :manpage:`pepsi-stage-bounce(1)`,
:manpage:`pepsi.conf(5)`.