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:
parent
555578bac5
commit
53ca30ad61
2 changed files with 21 additions and 5 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -99,9 +99,19 @@ paths:
|
|||
type: object
|
||||
required: [name, domain]
|
||||
properties:
|
||||
name: {type: string}
|
||||
domain: {type: string}
|
||||
title: {type: string}
|
||||
name:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 30
|
||||
pattern: '^[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*$'
|
||||
description: Local part of the list address, stored lowercase. Letters, digits, '.', '_' and '-' only, no dot at either end or two in a row.
|
||||
domain:
|
||||
type: string
|
||||
description: ASCII host name (labels of 1 to 63 letters, digits and hyphens).
|
||||
title:
|
||||
type: string
|
||||
maxLength: 200
|
||||
description: A single line without control characters. Defaults to the name.
|
||||
responses:
|
||||
'201':
|
||||
description: Created
|
||||
|
|
@ -131,7 +141,7 @@ paths:
|
|||
schema:
|
||||
type: object
|
||||
properties:
|
||||
title: {type: string}
|
||||
title: {type: string, minLength: 1, maxLength: 200, description: A single line without control characters.}
|
||||
post_policy: {type: string, enum: [members, moderated]}
|
||||
join_policy: {type: string, enum: [open, closed]}
|
||||
archive_policy: {type: string, enum: [public, private, off]}
|
||||
|
|
|
|||
Loading…
Reference in a new issue