CLI & configuration

Every MailDev command-line flag, environment variable, and configuration-file key, with defaults and precedence rules.

Usage #

maildev [options]
maildev init [--force] [--json]

Configuration comes from four places. Later entries win:

1. Defaults
2. A configuration file
3. Environment variables
4. Command-line flags

Scaffolding a config file #

maildev init walks you through the common settings and writes a configuration file in the current directory:

maildev init
maildev init --force   # overwrite an existing file
maildev init --json    # write .maildevrc.json rather than prompting for a format

Configuration files #

Searched in the current directory and then each parent, first match wins:

Point at a specific file with --config <path>.

{
  "smtp": 1025,
  "web": 1080,
  "maxEmails": 200,
  "mailDirectory": "./tmp/mail",
  "mcp": true
}

Keys are the camelCase form of the flag name: --base-pathname is basePathname, --max-emails is maxEmails.

SMTP server #

--hide-extensions accepts STARTTLS, PIPELINING, 8BITMIME, and SMTPUTF8. Hiding STARTTLS is the usual reason to reach for it — some clients upgrade opportunistically and then fail, and not advertising the extension is easier than fixing the client.

The default bind address :: accepts both IPv6 and IPv4 connections on most systems. If a client resolves localhost to ::1 and cannot connect, bind explicitly with --ip 0.0.0.0 or send to 127.0.0.1.

See HTTPS & TLS for the certificate flags in context.

Web UI, REST API, and MCP #

All three are served by one process on one port.

Setting --web-user and --web-pass puts HTTP basic auth in front of the UI and the whole REST API. /api/healthz stays unauthenticated on purpose, so container health checks keep working.

--base-pathname /maildev moves the UI, the API (/maildev/api), and the MCP endpoint (/maildev/mcp) under that prefix. That is what you want behind a reverse proxy — see HTTPS & TLS for an nginx example, including the websocket headers the live inbox needs.

Storage #

Without --mail-directory, messages live in memory and are gone when the process exits. With it, messages are written as files and restored on startup — so restarting MailDev keeps your inbox.

--max-emails bounds the store: once the limit is reached, the oldest message is discarded, and its files with it. Worth setting whenever you persist to disk or run a long test suite.

Relay & auto-relay #

MailDev can forward a caught message on to a real SMTP server — either on demand from the UI and API, or automatically for everything it receives.

With only the --outgoing-* flags set, nothing is forwarded until you ask for it — per message, from the UI or via POST /api/email/:id/relay.

--auto-relay forwards everything as it arrives. Given an address (--auto-relay you@example.com) it rewrites the recipient, which is how you get every test message into one real inbox.

Rules narrow that down. The last matching rule wins:

[
  { "allow": "*" },
  { "deny": "*@test.com" },
  { "allow": "ok@test.com" },
  { "deny": "*@utah.com" },
  { "allow": "johnny@utah.com" }
]

That relays everything except @test.com and @utah.com addresses, with ok@test.com and johnny@utah.com allowed back through.

maildev --outgoing-host smtp.gmail.com --outgoing-secure --outgoing-user you@gmail.com --outgoing-pass secret --auto-relay --auto-relay-rules relay-rules.json

MCP #

See the MCP guide for client configuration, and the standalone maildev-mcp stdio server for desktop AI tools.

Logging #

--log-mail-contents prints message bodies to stdout. Convenient when debugging a parser problem; do not leave it on in a shared log.

Other #

Examples #

A persistent inbox with MCP enabled and a bounded store:

maildev --mail-directory ./tmp/mail --max-emails 500 --mcp

Behind a reverse proxy at /maildev, with basic auth:

maildev --base-pathname /maildev --web-user dev --web-pass secret

CI: no UI, quiet, bounded:

maildev --disable-web --silent --max-emails 200

Different ports because something else owns the defaults:

maildev --smtp 2025 --web 8080

Edit this page·View as markdown