docs: Newsletters section in the README

- Publishers policy, sent-post statistics, priority, rate limit and the public subscribe form
- State what is not included: scheduled sends and open or click tracking
This commit is contained in:
tgiachi 2026-11-10 13:07:16 +01:00
commit 275b269977

View file

@ -20,6 +20,7 @@ A modern, single-binary mailing list manager: an evolution of Mailman.
send to `list+join@domain` or `list+leave@domain`, then reply to the confirmation. A reply works once, a request
expires after 72 hours, and a confirmation that could not be applied (closed list, database error) can be replied to again.
A member disabled by bounces can rejoin the same way.
- Newsletters: a `publishers` post policy, sent-post statistics, a relay rate limit and a public subscribe form.
- Moderated lists: posts wait in a queue that the API can approve or discard.
- VERP bounces: every recipient gets a signed return address; 3 hard bounces within 30 days disable a member.
- Archive with full-text search (SQLite FTS5) and threading. Each list has an
@ -56,6 +57,30 @@ The admin UI and the public archive, with demo data (`docs/screenshots/`).
![A public archive page with the thread of a message](docs/screenshots/public-archive.png)
## Newsletters
A newsletter is a list whose post policy is `publishers`: only members flagged as publishers may post, and everybody else just receives. Everything else (double opt-in, one-click unsubscribe, DKIM, archive, bounces, the queue) works as for a discussion list.
```sh
parsimony list set news@example.org --post publishers
parsimony member add news@example.org alice@example.com --publisher
parsimony member set news@example.org alice@example.com --publisher=false # demote
```
In the admin UI, pick "Publishers only (newsletter)" in the list's Settings tab and use the "Can publish" checkbox or the "Make publisher" action on the Members tab. The API uses `PATCH /api/v1/lists/{id}/members/{address}` with `{"publisher": true}`. `member import` accepts `email,name,publisher` lines. `member ls` shows each member's role.
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.
**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.
**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.
**Subscribe form.** A list whose archive is public and whose join policy is open gets a signup page at `/subscribe/{address}` on the public web listener, linked from its archive page. It sends the usual double opt-in message. The page that follows is always the same, whether or not the address is a member or the list qualifies for mail, so the form cannot be used to find out who is subscribed. A hidden field catches bots; each IP (the TCP peer, `X-Forwarded-For` is ignored) may post 10 times per hour, then gets `429`; behind a reverse proxy every visitor shares its address, so limit at the proxy too. The body is capped at 4 KiB.
Not included: scheduled sends and open or click tracking.
## Run
```