..
  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-smarthost
==============================

*Relay through a configured upstream smarthost.*

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:
:manpage:`pepsi-stage-relay-to-smarthost(1)`.

Features
========

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.

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

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.

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

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: :manpage:`pepsi-stage-relay-to-smarthost(1)`.

State
=====

Identical to :doc:`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.

See also
========

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