docs: list name, domain and title rules, confirmation behaviour

- openapi: name, domain and title constraints of POST /lists, title of PATCH
- README: the rules, the RFC 2047 List-Id, single-use and re-usable confirmation, rejoin after bounces
This commit is contained in:
tgiachi 2026-11-10 11:54:52 +01:00
commit 53ca30ad61

View file

@ -10,7 +10,9 @@ A modern, single-binary mailing list manager: an evolution of Mailman.
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.
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.
- 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 disable a member.
- Archive with full-text search (SQLite FTS5) and threading. Each list has an
@ -49,6 +51,10 @@ the daemon refuses to start otherwise. Leave it empty to turn the one-click link
curl -H "Authorization: Bearer $PARSIMONY_API_TOKEN" -d '{"name":"dev","domain":"example.org","title":"Dev"}' localhost:8080/api/v1/lists
```
A list `name` is 1 to 30 characters of `a-z`, `0-9`, `.`, `_` and `-` (upper case is lowered, no dot at either end), the `domain`
a host name, and the `title` one line of at most 200 characters without control characters; anything else is a 400.
The title is encoded (RFC 2047) in the `List-Id` header when it is not ASCII.
## Command line
The same binary is an administration client. It talks to the REST API, so it works against a local or remote daemon.