Configuration

Configuration is YAML, loaded from xlistman.yaml (or the file in $XLISTMAN_CONFIG). Every value can be overridden with an XLISTMAN_-prefixed environment variable, and ${ENV_VAR} syntax expands secrets from the environment. Unknown keys are rejected, so a typo fails loudly rather than silently.

Generate a fully commented config with:

./xlistman config init

and validate it with:

./xlistman config check

web.base_url and database.path are required. web.base_url must start with http:// or https:// — it’s the origin people see in emails.

Keys

Key	Environment variable	Default	Meaning
`http.listen`	`XLISTMAN_HTTP_LISTEN`	`:8080`	HTTP listen address — web UI and API.
`lmtp.listen`	`XLISTMAN_LMTP_LISTEN`	`:8024`	LMTP listen address for inbound mail. The LMTP server is unauthenticated — bind it to a private interface (`127.0.0.1:8024`) in production.
`socket.path`	`XLISTMAN_SOCKET_PATH`	`/tmp/xlistman.sock`	Pipe-mode Unix socket path used by `xlistman deliver`.
`database.path`	`XLISTMAN_DATABASE_PATH`	`./xlistman.db`	SQLite database file.
`smtp.host`	`XLISTMAN_SMTP_HOST`	`localhost`	Outbound SMTP relay host.
`smtp.port`	`XLISTMAN_SMTP_PORT`	`25`	Outbound SMTP relay port.
`smtp.username`	`XLISTMAN_SMTP_USERNAME`	(empty)	SMTP auth username; auth is used only when set.
`smtp.password`	`XLISTMAN_SMTP_PASSWORD`	(empty)	SMTP auth password — use `${ENV_VAR}`.
`smtp.mode`	`XLISTMAN_SMTP_MODE`	`smtp`	`smtp` (relay via the host above) or `sink` (write outbound mail to `sink_dir` — development only, no MTA needed).
`smtp.sink_dir`	`XLISTMAN_SMTP_SINK_DIR`	`./mail`	Directory for outbound mail in sink mode.
`web.base_url`	`XLISTMAN_WEB_BASE_URL`	(required)	Public origin used in emails (subscribe links, magic links).
`rate_limits.subscribe_per_hour`	`XLISTMAN_RATE_LIMITS_SUBSCRIBE_PER_HOUR`	`5`	Subscribe requests per email per hour.
`rate_limits.magic_link_per_hour`	`XLISTMAN_RATE_LIMITS_MAGIC_LINK_PER_HOUR`	`3`	Magic-link requests per email per hour.
`rate_limits.magic_link_per_ip_per_hour`	`XLISTMAN_RATE_LIMITS_MAGIC_LINK_PER_IP_PER_HOUR`	`50`	Magic-link requests per client IP per hour.
`rate_limits.posts_per_hour`	`XLISTMAN_RATE_LIMITS_POSTS_PER_HOUR`	`10`	Posts per sender per hour.
`queue.max_retries`	`XLISTMAN_QUEUE_MAX_RETRIES`	`8`	Delivery attempts before a post is bounced to its sender.

A minimal runnable example (this is what the Docker image ships):

http:
  listen: ":8080"
lmtp:
  listen: ":8024"
socket:
  path: "/tmp/xlistman.sock"
database:
  path: "./xlistman.db"
smtp:
  host: "localhost"
  port: 25
  mode: "smtp"
  sink_dir: "./mail"
web:
  base_url: "http://localhost:8080"
rate_limits:
  subscribe_per_hour: 5
  magic_link_per_hour: 3
  magic_link_per_ip_per_hour: 50
  posts_per_hour: 10
queue:
  max_retries: 8

Secrets

${ENV_VAR} in any string value is replaced from the environment at load time, so credentials never have to live in the file:

smtp:
  username: "relay"
  password: "${SMTP_PASSWORD}"

Per-list settings

List-level settings (moderation, digests, subscription policy, bounce threshold, attachment policy, and more) aren’t in this file — they’re set per list with xlistman list config <addr> <key>=<value> or in the list console. See The web UI and Command line.

Next: MTA integration.