Configuration

Configuration is YAML, loaded from xmailman.yaml (or the file in $XMAILMAN_CONFIG). Every value can be overridden with an XMAILMAN_-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:

./xmailman config init

and validate it with:

./xmailman 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`	`XMAILMAN_HTTP_LISTEN`	`:8080`	HTTP listen address — web UI and API.
`lmtp.listen`	`XMAILMAN_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`	`XMAILMAN_SOCKET_PATH`	`/tmp/xmailman.sock`	Pipe-mode Unix socket path used by `xmailman deliver`.
`database.path`	`XMAILMAN_DATABASE_PATH`	`./xmailman.db`	SQLite database file.
`smtp.host`	`XMAILMAN_SMTP_HOST`	`localhost`	Outbound SMTP relay host.
`smtp.port`	`XMAILMAN_SMTP_PORT`	`25`	Outbound SMTP relay port.
`smtp.username`	`XMAILMAN_SMTP_USERNAME`	(empty)	SMTP auth username; auth is used only when set.
`smtp.password`	`XMAILMAN_SMTP_PASSWORD`	(empty)	SMTP auth password — use `${ENV_VAR}`.
`smtp.mode`	`XMAILMAN_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`	`XMAILMAN_SMTP_SINK_DIR`	`./mail`	Directory for outbound mail in sink mode.
`smtp.tls`	`XMAILMAN_SMTP_TLS`	`starttls`	Transport security for the relay connection: `none`, `starttls` (opportunistic, the default), `starttls-required`, or `implicit` (TLS from the first byte, e.g. port 465). Credentials are only sent over an encrypted connection.
`smtp.tls_insecure_skip_verify`	`XMAILMAN_SMTP_TLS_INSECURE_SKIP_VERIFY`	`false`	Disable certificate verification for relays with self-signed or private-CA certificates. Off by default.
`web.base_url`	`XMAILMAN_WEB_BASE_URL`	(required)	Public origin used in emails (subscribe links, magic links).
`web.site_name`	`XMAILMAN_WEB_SITE_NAME`	`xMailman`	Instance name shown in page titles, the web UI header/footer, and social tags.
`rate_limits.subscribe_per_hour`	`XMAILMAN_RATE_LIMITS_SUBSCRIBE_PER_HOUR`	`5`	Subscribe requests per email per hour.
`rate_limits.magic_link_per_hour`	`XMAILMAN_RATE_LIMITS_MAGIC_LINK_PER_HOUR`	`3`	Magic-link requests per email per hour.
`rate_limits.magic_link_per_ip_per_hour`	`XMAILMAN_RATE_LIMITS_MAGIC_LINK_PER_IP_PER_HOUR`	`50`	Magic-link requests per client IP per hour.
`rate_limits.posts_per_hour`	`XMAILMAN_RATE_LIMITS_POSTS_PER_HOUR`	`10`	Posts per sender per hour.
`queue.max_retries`	`XMAILMAN_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/xmailman.sock"
database:
  path: "./xmailman.db"
smtp:
  host: "localhost"
  port: 25
  mode: "smtp"
  sink_dir: "./mail"
  tls: "starttls"
  tls_insecure_skip_verify: false
web:
  base_url: "http://localhost:8080"
  site_name: "xMailman"
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}"

Credentials are only ever sent over an encrypted connection: if smtp.username is set, the relay must offer STARTTLS (the smtp.tls default), or you must set smtp.tls: starttls-required or implicit. smtp.tls: none combined with a username is rejected when the config loads.

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 xmailman list config <addr> <key>=<value> or in the list console. See The web UI and Command line.

Next: MTA integration.