MailDev 3.0: a local SMTP catcher and web inbox, rewritten as a TypeScript monorepo

Version 3.0 is a full rewrite, and v2 stays the fallback

[email protected] was released on 23 September 2026, after release candidates on 6 July (rc.1) and 28 August (rc.3). The project calls it a complete rewrite and restructuring of the entire codebase that tries to minimize breaking changes, and it publishes an upgrade guide from v2 on maildev.github.io. The last push to the repository was on 24 September 2026, the day after the release.

The practical point is the escape hatch: if you run into problems with 3.0, the project's own advice is to install the latest v2 release from the v2 branch. A rewrite this fresh means you should keep that fallback in reach for the first weeks, and pin the version in CI rather than pulling whatever is newest.

One npm binary or one Docker image, each listening on two ports

There are two ways to run it. The npm route installs a global command:

npm install -g maildev

The Docker route uses the maildev/maildev image on Docker Hub and maps both ports:

docker run -p 1080:1080 -p 1025:1025 maildev/maildev

Port 1025 is the SMTP port that catches mail (-s, --smtp) and 1080 serves the web GUI (-w, --web). Your application should point its SMTP settings at 1025 and you read the results on 1080. Every command line option has a matching environment variable, such as MAILDEV_SMTP_PORT and MAILDEV_WEB_PORT, which is the convenient form inside a container. A --config option accepts a configuration file path instead.

Default binds put both services on every interface

The SMTP service binds to :: by default (--ip, MAILDEV_IP) and the HTTP service binds to 0.0.0.0 (--web-ip, MAILDEV_WEB_IP). On a laptop on a trusted network that is convenient. On a shared host, a cloud VM or an office network, it means the captured inbox is reachable from other machines, and that inbox holds whatever your application sent: password reset links, invitation tokens, customer test data.

MailDev does not lock this down for you. To restrict access, either bind to a specific address with --ip and --web-ip, or put the GUI behind HTTP authentication with --web-user and --web-pass. --https with --https-key and --https-cert switches the web interface from http to https, and --disable-web turns the GUI off entirely when you only need SMTP capture.

Mail is kept without limit unless --max-emails is set

MailDev keeps every email by default: --max-emails 0 means unlimited, which preserves the historical behaviour and keeps persisted mail durable across restarts. Mail is written to disk when you pass --mail-directory (MAILDEV_MAIL_DIRECTORY). A test suite that sends thousands of messages will grow that directory without bound.

Set a positive --max-emails to cap the store. When a new email arrives and the limit is reached, the oldest message is discarded along with its .eml file and attachments, so the mail directory stays bounded as well. A separate guard applies to single messages: --max-message-size defaults to 52428800 bytes, messages larger than that are rejected, and 0 disables the check. If your application sends large attachments, a rejected message here looks like a delivery failure in your app's logs.

Relay modes can send caught mail to a real SMTP server

MailDev can forward mail onward instead of only holding it. The --outgoing-host, --outgoing-port, --outgoing-user, --outgoing-pass and --outgoing-secure options describe the real SMTP server to relay through. --auto-relay switches on automatic relaying and takes an optional relay email address, and --auto-relay-rules points to a file of filter rules for that mode.

This is the one setting that turns a safe sandbox into something that delivers real email. With auto relay on and loose rules, messages your development environment generates for test accounts can reach actual recipients. Keep relay credentials out of shared configuration files and write the rules file before enabling --auto-relay.

Incoming SMTP can require authentication and TLS

On the receiving side, --incoming-user and --incoming-pass set the SMTP credentials clients must present, and --incoming-secure enables SMTP SSL for incoming mail, using the certificate and key from --incoming-cert and --incoming-key. This matters when your application refuses to send to an unauthenticated or plain-text server and you want the development setup to match production behaviour.

--hide-extensions takes a comma-separated list of SMTP extensions MailDev should not advertise, which lets you test how a client behaves when an extension is missing. For debugging, -v enables verbose logging, --log-mail-contents logs a JSON representation of each incoming mail, and --silent disables all output. --base-pathname sets the base path for URLs when the GUI sits behind a reverse proxy path.

The 3.0 code is a pnpm and Turbo monorepo with an MCP server

The repository root is a private @maildev/monorepo package pinned to [email protected], with the code split under packages/ and builds run through turbo run build. The Dockerfile starts from node:22-alpine, builds each package with tsc for core, smtp, api, mcp and cli and with Vite for the UI, then uses pnpm deploy to assemble a production-only tree with no dev dependencies or source. If you want to contribute or build the image yourself, that is the toolchain you need.

The mcp package backs a new --mcp flag (MAILDEV_MCP), which enables an MCP server for Claude integration. Like the rest of 3.0, it arrived in the rewrite, so treat it as new code.

Editorial conclusion

MailDev fits developers who want to see the email their app sends without delivering it, through one npm binary or one Docker image on ports 1025 and 1080. It is the wrong choice for anything exposed to other people unless you set --web-user and --web-pass or bind to a specific address. Before upgrading, read the v2 upgrade guide, since 3.0 is a full rewrite and the project itself names the latest v2 release as the fallback.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes