feat: document the queue, close mutation gaps, plain relay errors

- Document delivery semantics, retries and the queue API in the README and OpenAPI
- Add relay.concurrency to the example config
- Test that a relay problem never counts against a member, that the longest-waiting delivery goes first, and the error and limit details
- Show the plain relay error when there is a single batch
This commit is contained in:
tgiachi 2026-11-09 16:04:45 +01:00
commit 6461e77a95

View file

@ -5,6 +5,9 @@ A modern, single-binary mailing list manager: an evolution of Mailman.
- Postfix delivers to parsimony over LMTP; parsimony relays through SMTP.
- Discussion lists with member-only posting, `List-*` headers, one-click unsubscribe
and DMARC-safe `From` rewriting.
- Durable outbound queue: a post is accepted once it is stored, one delivery per recipient,
and a background worker sends it with retries (1m, 5m, 15m, 1h, 3h, then every 6h, for up to
3 days). Relay outages and restarts lose nothing.
- Self-service subscribe and unsubscribe by email with double opt-in:
send to `list+join@domain` or `list+leave@domain`, then reply to the confirmation.
- Moderated lists: posts wait in a queue that the API can approve or discard.
@ -42,6 +45,18 @@ the unsubscribe links in every message use it. Keep the `api` listener private.
curl -H "Authorization: Bearer $PARSIMONY_API_TOKEN" -d '{"name":"dev","domain":"example.org","title":"Dev"}' localhost:8080/api/v1/lists
```
## Delivery and the queue
LMTP answers `250` when the post is in the queue, so a down relay never bounces mail back to Postfix.
It answers `451` only when the database itself fails.
- Temporary relay errors (4xx, timeouts, connection failures) are retried with backoff.
- A permanent rejection (5xx) drops that delivery. Only a bad-mailbox reply (`5.1.x`) counts as a hard
bounce for the member; errors such as "relay access denied" never disable members.
- Delivery is at-least-once: a crash between the relay accepting a message and the queue entry being
removed can send one message to one recipient twice.
- `GET /api/v1/queue` and the Queue page show what is pending or failing, and a stuck delivery can be discarded.
## Admin UI
The UI is a single-page app in `admin/`, built into `internal/adminui/dist` and embedded in the binary.