docs: say what the second review found about newsletters, priority and shutdown

- Warn that forged publisher senders are not checked by the daemon
- Describe the real limits of the delivery priority
- Document the Docker stop timeout and three known gaps
This commit is contained in:
tgiachi 2026-11-10 15:06:35 +01:00
commit c6cbcb3d3b

View file

@ -71,9 +71,11 @@ In the admin UI, pick "Publishers only (newsletter)" in the list's Settings tab
A publisher's post passes the same identity check as any post: the `From` header must name the SMTP sender, or the post is held. A post from anyone else, member or not, is refused with `550 5.7.1`; it is never held, archived or queued. A publisher disabled by bounces can still post.
**Protect the publishers' addresses.** Parsimony does not verify SPF, DKIM or DMARC on inbound mail, and every issue carries the publisher's address in `Reply-To`, so subscribers learn it. Anyone who can send mail to your MX with that address as the sender and in `From` can mail the whole subscriber base. Make Postfix reject forged senders (see Security notes), and keep the list of publishers short.
**Sent posts.** Each post queued to a list is recorded with its subject, time and number of recipients, and the queue counts how its deliveries end: **sent** (accepted by the relay), **failed** (refused, or still failing after 3 days), **dropped** (the mailbox does not exist, or the delivery was discarded) and **pending**. A count changes in the same transaction as the delivery. See them with `parsimony posts ls news@example.org`, `GET /api/v1/lists/{id}/posts`, or the Sent tab of a list, which refreshes every 5 seconds while something is pending. Posts are kept for 400 days. Parsimony does not track opens or clicks.
**Priority.** Newsletter deliveries go out after everything else that is due, so a big newsletter never delays discussion mail or confirmations.
**Priority.** Newsletter deliveries go out after everything else that is due, so discussion mail and confirmations that are due go first. A batch of newsletter deliveries already taken by the worker is paced to the end, so with a low `relay.rate_per_second` a confirmation can wait for up to that batch (50 deliveries divided by the rate). Sustained discussion traffic at the paced rate can delay a newsletter without limit; a delivery that waited more than 3 days is given up at its first temporary failure.
**Rate limiting.** Relays such as Amazon SES throttle sending. Set `relay.rate_per_second` to the most sends the daemon may start in one second (default `0`, unlimited). One pacer sits in front of every send attempt, retries included, and spaces them evenly. Set it a little under your relay's limit (12 for a limit of 14). Each recipient is one message, so a post to N members takes about N divided by the rate in seconds.
@ -351,6 +353,8 @@ lists.example.org lmtp:inet:127.0.0.1:2424
(`openssl rand -hex 24` makes a good one). After 10 wrong or missing tokens within 5 minutes an address is
locked out for 5 minutes (HTTP 429, valid token included). The address is the TCP peer: behind a reverse proxy
every client shares the proxy's address, so rate-limit at the proxy as well.
- **Stopping.** The daemon finishes in-flight mail on SIGTERM and waits up to 30 s, idle LMTP connections included; Docker's default `docker stop` grace period is 10 s, so run the container with `--stop-timeout 35`.
- **Known gaps.** A held message that the sender retries after a lost `250` is held twice, and approving both delivers both; the admin sees a held message's summary but not its body before approving; a member's responder that tags its replies `Auto-Submitted: auto-generated` and answers the list address is delivered as a normal post until a human notices.
- The API and the admin UI use one bearer token and no TLS: put them behind a reverse proxy with TLS and keep the `api`
listener private.