..
  This file is part of PEPSI.
  Copyright (C) 2026 GNUnet e.V.

  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-status
============

*Summarise the health of the mail pipeline.*

Role
====

``pepsi-status`` is the operator's read-only health overview of the pipeline. It
connects through the shared ``[pepsi-postgres]`` section, has no section of its
own (the only other option it reads is ``[pepsi] MAILBOX_QUOTA``, the site
default an account with no row of its own inherits), and never modifies a row or
issues a notification, so it is safe to run over SSH against a live deployment. Started as ``root`` it continues as the
``pepsi`` service account before connecting, so no ``sudo -u pepsi`` is needed.
Reference: :manpage:`pepsi-status(1)`.

Features
========

* **Queue** — the ``pepsi.workqueue`` backlog broken down by ``stage`` and
  ``status``, with the age of the oldest message in each bucket.
* **Stuck messages** — the individual ``failed``/``timeout`` messages, oldest
  first, with every reason recorded for them: the structured next-hop failure
  from ``state.bounce`` (remote MTA, SMTP code, enhanced status, reply text), the
  stage's own ``state.last_error``, and the dispatcher's
  ``state.dispatch_error`` (a crashed or hung worker, an unconfigured stage);
  capped by ``--limit``.
* **Delivery & failures** — cumulative ``dispatch_stats``/``stage_stats``
  counters: total messages processed, per-stage message counts, average
  processing time, worker timeouts and crashes.
* **Outbound TLS** — ``tls_session`` outcomes of the last seven UTC report-days
  (today's included) grouped by policy domain and
  result type (non-successful results marked), plus MX addresses the resolver
  cache has flagged as failing to connect.
* **Mailbox quotas** — every account with quota accounting, oldest measurement
  first (the order :doc:`pepsi-quota`'s ``reconcile`` sweep works in), with its
  effective limit, the measured usage, the un-measured delivery estimate on top
  of it and the age of the measurement. An account appears here once something
  has been delivered to it, quota or no quota.

``--json`` emits the whole report as one JSON object for monitoring systems, and
``--limit`` caps both the stuck-message list and the mailbox-quota list.

A note on "recent successes"
============================

A successfully delivered message is *deleted* from the queue, so there is no
per-message delivery log. The delivery figures are therefore the cumulative
counters accumulated since the schema was created — lifetime totals, not a
rolling time window. Only the queue snapshot and the TLS section (which is keyed
by report-day) reflect genuinely recent activity.

See also
========

:doc:`pepsi-queue`, :doc:`pepsi-quota`, :doc:`pepsi-tlsrpt`,
:doc:`pepsi-dispatch`, :doc:`../architecture`, :manpage:`pepsi-status(1)`,
:manpage:`pepsi.conf(5)`.