- Judge membership on the envelope sender and require the From header to name the same address - Hold mismatches (and missing, unparsable or multiple From addresses) for the admin instead of delivering - Record why a message was held: new held.reason column, migrated, shown in the API, CLI and UI - Accept an empty message in the held queue - Document who may post
12 KiB
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-safeFromrewriting. - 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@domainorlist+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) oroff. 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(seedocs/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; no authentication, see Security notes |
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):
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-Unsubscribeheaders 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 theList-*headers. A relay may addReceivedor 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 -allon 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 127.0.0.1:8080:8080 -p 8081:8081 parsimony
Use db: /data/parsimony.db in the config. Do not publish the LMTP port (2424): Postfix reaches it over a Docker network
shared with the container, and lmtp.allow should list that network's range (see Security notes). 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/queueand 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
Security notes
-
LMTP has no authentication. Whoever can connect to it can send mail as any member. Keep it on
127.0.0.1, on a private network, or on a unix socket, and list the clients that may connect:lmtp: addr: 0.0.0.0:2424 allow: [172.16.0.0/12] # CIDR ranges or single addresses; other clients are dropped before the greetingThe daemon logs a warning at startup when LMTP is reachable beyond the machine and
lmtp.allowis empty.allowdoes not apply to unix sockets: use the permissions of the socket file. -
Who is posting. A post is accepted when the SMTP sender is a member and the
Fromheader names the same address. The SMTP sender can be forged by anyone who can send mail to your MX, and the archive, the rewrittenFromandReply-Tocome from the header; so a post whose header names someone else (or has no usableFrom, or several addresses) is held for moderation instead of delivered, with the reason shown to the admin (API, CLI, UI). Let Postfix reject forged senders too (SPF, DKIM, DMARC checks on inbound mail). -
The API and the admin UI use one bearer token and no TLS: put them behind a reverse proxy with TLS and keep the
apilistener private.
Licence
Parsimony is free software, released under the GNU General Public License, version 3 or (at your option) any later
version. See 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.