Modern single-binary mailing list manager
  • Go 79.3%
  • TypeScript 19.4%
  • CSS 0.5%
  • Python 0.4%
  • Dockerfile 0.2%
  • Other 0.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
tgiachi 45a61ef294 feat(archive): import messages from an mbox
- Add ImportMbox: batches of 200, idempotent by Message-ID, threads rebuilt at the end
- Date fallbacks: Date header, then the From line, then the import time
- Report failed and oversized messages without stopping, keep progress on a read error
- Import regardless of the list's archive policy
2026-11-09 17:14:46 +01:00
.forgejo/workflows ci: Forgejo Actions workflows and make targets 2026-11-09 17:03:17 +01:00
admin feat: document the queue, close mutation gaps, plain relay errors 2026-11-09 16:04:45 +01:00
docs feat(admin): outbound queue page 2026-11-09 15:55:52 +01:00
e2e feat(cli): command-line client for administration 2026-11-09 16:57:25 +01:00
internal feat(archive): import messages from an mbox 2026-11-09 17:14:46 +01:00
.dockerignore feat(admin): build tooling, Docker stage and docs; close test gaps 2026-11-09 15:42:07 +01:00
.gitignore feat(adminui): embed the admin SPA and serve it next to the API 2026-11-09 15:29:12 +01:00
Dockerfile feat(cli): command-line client for administration 2026-11-09 16:57:25 +01:00
go.mod feat(archive): parse messages into archivable entries 2026-11-09 15:18:23 +01:00
go.sum feat(archive): parse messages into archivable entries 2026-11-09 15:18:23 +01:00
Makefile ci: Forgejo Actions workflows and make targets 2026-11-09 17:03:17 +01:00
parsimony.example.yaml feat: document the queue, close mutation gaps, plain relay errors 2026-11-09 16:04:45 +01:00
README.md docs: describe the CI workflows and make ci 2026-11-09 17:04:40 +01:00

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.
  • 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 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.

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