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:
parent
f3c75dc97d
commit
6461e77a95
1 changed files with 83 additions and 10 deletions
15
README.md
15
README.md
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue