..
  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-relay-to-maildir
============================

*Deliver to local users' Maildirs; forward the rest.*

Role
====

``pepsi-stage-relay-to-maildir`` is the local-delivery stage. For each envelope
recipient it decides whether the address is *local* and, if so, writes the
message into that user's ``Maildir/new/`` via the setuid-root
:manpage:`pepsi-helper-maildir-writer(1)` helper; every other recipient is
forwarded to ``NEXT_STAGE``. Reference: :manpage:`pepsi-stage-relay-to-maildir(1)`.

Features
========

Local recipient matching
-------------------------

* A recipient is local when its domain is in ``LOCAL_DOMAINS`` (default
  ``[pepsi-ingress] ACCEPTED_DOMAINS``), its mailbox name resolves to a passwd
  entry, and that uid is permitted by ``TARGETS``.
* ``TARGETS`` is an allow-list of user names, uids, and uid ranges
  (``alice``, ``452``, ``1000-1100``, ``10000-``); it defaults to the regular
  (non-system) uid range from ``/etc/login.defs``.
* The mailbox name is the local-part with any ``RECIPIENT_DELIMITER`` sub-address
  (default ``+``) stripped, lower-cased.

Partial delivery
----------------

* Local recipients are written to their Maildirs; the remaining recipients are
  split onto a new ``pending`` row at ``NEXT_STAGE`` (a smarthost relay, or a
  bounce stage when no smarthost is configured).
* Two addresses for the same local account are delivered only once.
* Each local copy gets a ``Return-Path:``, a ``Delivered-To:`` loop guard and a
  ``Received:`` trace header prepended.

Retry, bounce and DSN
---------------------

* A helper-reported failure (e.g. a full disk) pauses that recipient with
  **exponential backoff** up to ``MAX_LIFETIME``, then routes it to
  ``BOUNCE_STAGE`` (honouring the sender's ``NOTIFY``). A bounce is never
  re-bounced.
* Originates a positive DSN on successful local delivery when
  ``[pepsi] ORIGINATE_SUCCESS_DSN`` is set and the recipient asked for
  ``NOTIFY=SUCCESS``.

Privilege model
---------------

* The stage binary is installed **setgid** ``pepsi-maildir`` (mode ``2755``).
  The dispatcher runs it as the unprivileged ``pepsi`` user; the setgid bit
  grants the effective gid needed to exec the group-restricted helper — and
  nothing else on the host gains that ability.

Configuration
=============

``[stage-<name>]`` with ``PROGRAM = pepsi-stage-relay-to-maildir``:
``SERVER_NAME`` *(required)*, ``TARGETS``, ``LOCAL_DOMAINS``,
``RECIPIENT_DELIMITER``, ``HELPER``, ``NEXT_STAGE``/``BOUNCE_STAGE`` and the
retry policy (``RETRY_INITIAL``/``RETRY_MAX_INTERVAL``/``RETRY_FACTOR``/
``MAX_LIFETIME``). Full reference: :manpage:`pepsi-stage-relay-to-maildir(1)`.

State
=====

* **Inputs:** ``state.dsn`` (per-recipient ``NOTIFY``/``ORCPT``) and
  ``state.local_origin``.
* **Outputs:** ``attempts``/``last_error`` on pause; a ``state.bounce`` object on
  the rows enqueued for the bounce stage; the per-recipient ``state.dsn`` is
  sliced onto each split row. ``state.dsn``/``state.origin`` are preserved.

See also
========

:doc:`pepsi-stage-relay-to-smarthost`, :doc:`pepsi-stage-relay-to-internet`,
:doc:`pepsi-stage-bounce`, :doc:`../features`,
:manpage:`pepsi-stage-relay-to-maildir(1)`.