CLI Flags & Environment Variables

Configuration is resolved in this precedence order: CLI flags > environment variables > TOML file > defaults.

Reference

CLI Flag	Environment Variable	Default	Description
--bind	RUSTMAIL_BIND	127.0.0.1	IP address to bind SMTP and HTTP listeners to. Docker images default to 0.0.0.0. Use 0.0.0.0 for remote access outside Docker.
--smtp-port	RUSTMAIL_SMTP_PORT	1025	SMTP listener port
--http-port	RUSTMAIL_HTTP_PORT	8025	HTTP and WebSocket port
--db-path	RUSTMAIL_DB_PATH	<data dir>/rustmail/rustmail.db (macOS: ~/Library/Application Support, Linux: ~/.local/share)	Path to the SQLite database file
--retention	RUSTMAIL_RETENTION	0	Auto-delete messages after N hours. 0 = keep forever.
--max-messages	RUSTMAIL_MAX_MESSAGES	0	Maximum messages to retain. Oldest are purged when exceeded. 0 = unlimited.
--max-message-size	RUSTMAIL_MAX_MESSAGE_SIZE	10485760	Maximum accepted message size in bytes (default: 10 MB).
--smtp-tls-cert	RUSTMAIL_SMTP_TLS_CERT	—	Path to a PEM certificate used to enable optional SMTP STARTTLS. Must be set together with --smtp-tls-key.
--smtp-tls-key	RUSTMAIL_SMTP_TLS_KEY	—	Path to a PEM private key used to enable optional SMTP STARTTLS. Must be set together with --smtp-tls-cert.
--ephemeral	RUSTMAIL_EPHEMERAL	false	Use in-memory SQLite. No data is written to disk.
--webhook-url	RUSTMAIL_WEBHOOK_URL	—	HTTP endpoint to POST to on every new message.
--log-level	RUSTMAIL_LOG_LEVEL	info	Log verbosity: trace, debug, info, warn, error.
--release-host	RUSTMAIL_RELEASE_HOST	—	Allowed SMTP target for email release in host:port format (e.g. smtp.example.com:587). Release is disabled unless set.
--allowed-origin	RUSTMAIL_ALLOWED_ORIGINS	—	Extra origin allowed to open the WebSocket, as scheme://host[:port]. Repeat the flag or comma-separate the variable. The origin RustMail is served on is always allowed.
--allowed-host	RUSTMAIL_ALLOWED_HOSTS	—	Host name browsers may reach RustMail on, as a bare name. Repeat the flag or comma-separate the variable. IP addresses and localhost are always answered.
--ws-buffer	RUSTMAIL_WS_BUFFER	4096	WebSocket events buffered for each client. A client that falls further behind is disconnected and resyncs when it reconnects. Must be at least 1.
--config	—	—	Path to an optional TOML configuration file.

STARTTLS is advertised on the normal SMTP port only when both TLS paths are configured; setting only one fails startup. After the client upgrades the connection, it must send EHLO again before continuing the session.

Examples

# Bind to all interfaces on custom ports
rustmail serve --bind 0.0.0.0 --smtp-port 2525 --http-port 9025

# Keep only the last 24 hours of email, max 1000 messages
rustmail serve --retention 24 --max-messages 1000

# Enable webhook notifications
rustmail serve --webhook-url https://hooks.example.com/email

# Enable optional SMTP STARTTLS on the existing SMTP port
rustmail serve --smtp-tls-cert ./certs/localhost.pem --smtp-tls-key ./certs/localhost-key.pem

# Allow releasing emails to a specific SMTP server
rustmail serve --release-host smtp.mailgun.org:587

# Behind a reverse proxy serving RustMail at https://mail.example.com
rustmail serve --allowed-origin https://mail.example.com

Hosts and origins

RustMail is a development tool with no authentication, so it takes care not to answer pages it was not opened by.

• Host decides whether a browser gets an answer at all. An IP address, localhost and *.localhost always do: neither can be pointed at another machine by someone else's DNS. Any other name (a reverse proxy's public name, a Docker service name, a .local name) has to be named with --allowed-host, otherwise the request is refused with 403. This is what closes DNS rebinding, where an attacker's domain is re-pointed at the machine running RustMail and every other check sees a same-origin request.
• Origin decides whether a browser may open the WebSocket. The origin RustMail is served on may; others need --allowed-origin. See WebSocket.

Naming an origin also allows its host, so a reverse-proxy deployment does not have to write the same name twice:

rustmail serve --allowed-origin https://mail.example.com

Neither check applies to clients that are not browsers, because DNS rebinding is an attack on browsers alone. A request is taken for a browser's when it carries Sec-Fetch-* (which a page cannot strip, and which every engine has sent since March 2023), an Origin, or a Mozilla/ user agent (which covers older browsers). A CI script, curl, the TUI and rustmail-action match none of those and are answered on any host.