- Require Go 1.27.3: fixes the standard library vulnerabilities govulncheck reported - Add the GPLv3 text and the licence note - Move shadcn to devDependencies: npm audit finds nothing in production dependencies - Add make lint (staticcheck) to go-ci and a separate vuln job in CI - Fix the staticcheck warning in a test
202 lines
10 KiB
Markdown
202 lines
10 KiB
Markdown
# parsimony
|
|
|
|
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.
|
|
- DKIM signing of outgoing mail with one key per list domain, so DMARC holds after the From rewrite.
|
|
- 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.
|
|
- 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
|
|
`archive_policy`: `private` (default, API only), `public` (web pages) or `off`.
|
|
Public pages hide email addresses.
|
|
- Per-recipient one-click unsubscribe links (RFC 8058) with signed tokens.
|
|
- SQLite storage, one YAML config file.
|
|
- Command-line client for administration and scripts (`parsimony list|member|held|archive|queue`).
|
|
- Admin REST API under `/api/v1` (see `docs/openapi.yaml`).
|
|
- Admin web UI (Vite, React, shadcn/ui) served by the API listener at `/`: lists, settings,
|
|
members, held queue and archive.
|
|
|
|
## Run
|
|
|
|
```
|
|
cp parsimony.example.yaml parsimony.yaml
|
|
PARSIMONY_API_TOKEN=<token> go run ./cmd/parsimony serve -config parsimony.yaml
|
|
```
|
|
|
|
The API is disabled when `PARSIMONY_API_TOKEN` is not set.
|
|
|
|
Three listeners, each configurable:
|
|
|
|
| Listener | Default | Purpose |
|
|
|----------|---------|---------|
|
|
| `lmtp` | `127.0.0.1:2424` | mail from Postfix |
|
|
| `api` | `127.0.0.1:8080` | admin REST API, bearer token |
|
|
| `web` | `127.0.0.1:8081` | public archive and unsubscribe pages (`""` disables) |
|
|
|
|
Put the `web` listener behind a reverse proxy with TLS and set `base_url` to its public URL:
|
|
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
|
|
```
|
|
|
|
## Command line
|
|
|
|
The same binary is an administration client. It talks to the REST API, so it works against a local or remote daemon.
|
|
|
|
```
|
|
export PARSIMONY_API_TOKEN=... # the token is never a flag
|
|
export PARSIMONY_URL=http://127.0.0.1:8080 # default; --url overrides
|
|
|
|
parsimony list add dev@example.org --title "Developers"
|
|
parsimony list set dev@example.org --post moderated --archive public
|
|
parsimony member add dev@example.org alice@example.com --name Alice
|
|
parsimony member import dev@example.org subscribers.txt # "email[,name]" per line, "-" reads stdin
|
|
parsimony held ls dev@example.org
|
|
parsimony held approve 12
|
|
parsimony archive ls dev@example.org --q "deploy"
|
|
parsimony archive import dev@example.org dev.mbox # an mbox file or "-" for stdin
|
|
parsimony queue ls
|
|
parsimony --json list ls # JSON for scripts
|
|
parsimony help
|
|
```
|
|
|
|
`<list>` is an address or a numeric id. Destructive commands (`list rm`, `archive rm`) need `--yes`.
|
|
Exit status: 0 success, 1 failure (including lines that failed in `member import`), 2 usage error.
|
|
`parsimony serve -config FILE` runs the daemon; the old `parsimony -config FILE` form still works.
|
|
In the container: `docker exec parsimony /parsimony list ls`.
|
|
|
|
## Migrating from Mailman
|
|
|
|
Both Mailman 2 and Mailman 3 (HyperKitty) can export a list's history as an mbox file.
|
|
|
|
```
|
|
parsimony list add dev@example.org --title "Developers"
|
|
parsimony member import dev@example.org subscribers.txt # "email[,name]" per line
|
|
parsimony archive import dev@example.org dev.mbox
|
|
```
|
|
|
|
The import reads standard mbox (a message starts at a `From addr Tue Jan 2 15:04:05 2024` line, `>From ` escapes are
|
|
restored), decodes encoded headers, charsets and multipart bodies, and stores the plain text. It is safe to repeat: a
|
|
message already in the archive (same `Message-ID`) is skipped. Threads are rebuilt from `In-Reply-To` whatever the order
|
|
of the messages. Messages that cannot be read are listed and counted, and the exit status is 1; the others are kept.
|
|
It works whatever the list's archive policy is (the policy only governs live mail). The admin UI has the same import on
|
|
the Archive tab. Search is accent-insensitive: `caffe` finds "Caffè".
|
|
|
|
## Outgoing mail: DKIM, SPF and DMARC
|
|
|
|
Parsimony rewrites `From` to the list address, so a signature of the original author's domain is of no use and
|
|
receivers that enforce DMARC need a signature of the **list domain**.
|
|
|
|
```
|
|
parsimony dkim keygen lists.example.org --selector mail --out /etc/parsimony/dkim-lists.pem
|
|
```
|
|
|
|
prints the DNS TXT record to publish and the config to add (the private key is written with mode 0600 and the
|
|
command never overwrites an existing key without `--force`):
|
|
|
|
```yaml
|
|
dkim:
|
|
- domain: lists.example.org
|
|
selector: mail
|
|
key_file: /etc/parsimony/dkim-lists.pem
|
|
```
|
|
|
|
Once the record is in DNS, `parsimony dkim check lists.example.org --key FILE --selector mail` looks it up and compares it
|
|
with the key. Both commands work offline of the API and need no token.
|
|
|
|
- A message is signed with the key of the domain in its From address (exact match, else a parent domain), at send time, so
|
|
the per-recipient `List-Unsubscribe` headers are covered. Relaxed/relaxed, SHA-256, no body length limit.
|
|
Signed: From, To, Cc, Subject, Date, Message-ID, In-Reply-To, References, Reply-To, MIME-Version, Content-Type,
|
|
Content-Transfer-Encoding and the `List-*` headers. A relay may add `Received` or rewrite other headers.
|
|
- A list on a domain without a key is sent unsigned. A broken key file stops the daemon at startup. If signing fails at
|
|
send time the error is logged and the message goes out unsigned: not delivering is worse than a missed signature.
|
|
- RSA (2048 bits recommended; PKCS#1 or PKCS#8 PEM) and Ed25519 keys are supported. Some receivers do not verify Ed25519 yet.
|
|
- Also publish SPF for the machine that relays your mail (for example `v=spf1 ip4:203.0.113.10 -all` on the list domain)
|
|
and a DMARC record (start with `_dmarc.lists.example.org TXT "v=DMARC1; p=none; rua=mailto:postmaster@example.org"`,
|
|
then tighten the policy once the reports look clean).
|
|
|
|
## Docker
|
|
|
|
The image runs as an unprivileged user (uid 65532) and works with a read-only root filesystem.
|
|
Config is mounted read-only; the only writable path is the `/data` volume (the database).
|
|
|
|
```
|
|
docker build -t parsimony .
|
|
docker run -d --name parsimony --read-only --cap-drop ALL \
|
|
-v parsimony-data:/data \
|
|
-v $PWD/parsimony.yaml:/etc/parsimony/parsimony.yaml:ro \
|
|
-e PARSIMONY_API_TOKEN=... -p 2424:2424 -p 8080:8080 -p 8081:8081 parsimony
|
|
```
|
|
|
|
Use `db: /data/parsimony.db` in the config. A new named volume gets the right ownership by itself;
|
|
for a bind mount, make the host directory writable by uid 65532.
|
|
|
|
## 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.
|
|
It is served on the API listener together with `/api`, so it needs no CORS, and only when
|
|
`PARSIMONY_API_TOKEN` is set. You sign in with that token (kept in `sessionStorage`, gone when the tab closes).
|
|
|
|
```
|
|
make admin # npm ci && npm run build
|
|
make build # go build, embeds the UI
|
|
make test # go test + vitest
|
|
make ci # what CI runs: gofmt, vet, race tests, frontend tests and build
|
|
make e2e # end-to-end with a real Postfix in Docker (about 2 minutes, mostly the image build)
|
|
```
|
|
|
|
Without `make admin` the binary still builds and the UI answers 503 with a hint.
|
|
For frontend work run the daemon, then `cd admin && npm run dev` (Vite proxies `/api` to `127.0.0.1:8080`).
|
|
|
|
## Continuous integration
|
|
|
|
`.forgejo/workflows/ci.yaml` runs on Forgejo Actions (Codeberg) for pushes to `main` and for pull requests:
|
|
a Go job (`make go-ci`: gofmt, `go vet`, tests with the race detector) and an admin UI job (`make admin-ci`:
|
|
`npm ci`, tests, type check, build). Enable Actions in the repository settings and provide a runner with the
|
|
`docker` label (change `runs-on` if yours is named differently). `make ci` does the same locally.
|
|
`.forgejo/workflows/e2e.yaml` runs the Postfix end-to-end test on demand, because it needs a runner that can run Docker.
|
|
|
|
## End-to-end test
|
|
|
|
`make e2e` starts a real Postfix and parsimony in Docker and walks the whole path: Postfix hands list mail to
|
|
parsimony over LMTP, parsimony queues it and relays the copies back through Postfix, which delivers them to
|
|
maildirs. It checks the list headers and VERP return path, a real `550 5.1.1` from Postfix disabling a member after
|
|
three hard bounces, a real LMTP `550` for a non-member, join and leave by email, moderation, the public archive
|
|
and one-click unsubscribe. The files are in `e2e/` and behind the `e2e` build tag, so `go test ./...` stays fast.
|
|
|
|
## Postfix
|
|
|
|
Deliver the list domains to parsimony over LMTP and keep the `+` extensions intact, for example:
|
|
|
|
```
|
|
transport_maps = hash:/etc/postfix/transport
|
|
# /etc/postfix/transport
|
|
lists.example.org lmtp:inet:127.0.0.1:2424
|
|
```
|
|
|
|
## Licence
|
|
|
|
Parsimony is free software, released under the GNU General Public License, version 3 or (at your option) any later
|
|
version. See [LICENSE](LICENSE). The components in `admin/src/components/ui` come from shadcn/ui (MIT); the Go
|
|
dependencies (go-smtp, go-message, go-msgauth, modernc.org/sqlite, yaml.v3) use MIT, BSD or Apache 2.0 licences, which are
|
|
compatible with the GPL.
|