Troubleshooting & FAQ

The most common failure by far is mail not flowing: the list works in the web UI but nothing gets delivered, or posts go nowhere. Everything below starts from that reality.

“Nothing is being delivered to subscribers”

Work the loop in order.

1. Is outbound mail being sent at all? Check the queue and the logs. Try xlistman queue list — stuck messages show their retry count. If the queue is empty and nothing arrived, outbound was never attempted.
2. Is smtp.host reachable from the xListman host? The queue relays via smtp.host:smtp.port. Your MTA must accept the relay from this host (for loopback, Postfix’s mynetworks must allow it).
3. Is web.base_url right? It’s the origin in every email — if it’s wrong, links in emails point nowhere. It must start with http:// or https://.
4. For a first test, use smtp.mode: sink. Outbound mail becomes files in smtp.sink_dir instead of being relayed. If those appear, xListman is doing its job and the problem is the MTA, not xListman.

“Posts to the list don’t get in”

The inbound leg is your MTA delivering the list domain to xListman over LMTP (or the pipe socket).

1. Did you configure the MTA at all? See MTA integration. The two-line Postfix wiring, or the exim manualroute router, is what hands mail to xListman.
2. Is the LMTP server bound somewhere the MTA can reach it? In production it’s usually 127.0.0.1:8024; make sure lmtp.listen matches what your MTA targets.
3. Is the daemon running? LMTP and the pipe socket are served by xlistman serve. No daemon, no inbound mail.
4. The mydestination trap (Postfix). If the list domain is in mydestination, Postfix applies local_recipient_maps and rejects dev-subscribe@… as an unknown local user. The domain belongs in virtual_mailbox_domains only.
5. The exim loop guard. exim won’t route to its own SMTP interface (127.0.0.1). Use a second loopback address (127.0.0.2) as the LMTP target.

“A subscriber was silently removed / stopped receiving posts”

They probably weren’t removed — they were disabled by the bounce threshold. Bounced messages are attributed per subscription via VERP; at the list’s bounce_threshold (5 by default) the subscription auto-disables, and the owner can be notified. Re-enable from /me, by email (re-enable), or by an owner. Re-enabling resets the bounce count.

“My binary has no web UI”

A plain go build or go install produces a CLI-and-mail binary without the web UI — the frontend is built and embedded only in Docker images and release binaries. Use those, or build the web UI first (cd web && pnpm install && pnpm build). See Install.

“I sent a post and got no confirmation / no error”

Posts to a discussion list go out silently when moderation is off. If moderation is on, the post is held and you get a notice. Check the moderation queue and the archive for what actually happened. Unknown commands and rejected posts always produce a reply — silence usually means the message never reached xListman.

“My magic link didn’t arrive, or the page says sign-in is disabled”

• Magic links are rate-limited per address and per IP; too many requests and new ones are refused for the hour.
• login may be disabled instance-wide — xlistman web status shows the state, and xlistman enable login turns it back on (an Administrator action).

“My held message vanished”

Held messages expire after held_expiry_days (14 by default) and are silently discarded. Same for confirmation and moderation tokens. If a post sat in the queue longer than that, it’s gone by design.

“The config didn’t load”

xlistman config check will tell you. Unknown keys are rejected, so a typo fails loudly. web.base_url and database.path are required.

Is it production-ready?

Active, pre-1.0. The 0.x version reflects that the storage and config surface may still evolve — don’t build irreversible automation on it yet. The security policy and contribution path live in the repository.