MailDev 3.0: A Rewritten SMTP Test Server with a Web GUI

The Problem: Email Testing Without a Mail Server

Every project that sends email eventually needs to verify the content, headers, and attachments without spamming real recipients. Setting up a local SMTP server or using a shared test mailbox is slow and fills your inbox with noise. MailDev solves this by running an SMTP server on your machine that catches all incoming mail and displays it in a web interface. It is aimed at developers who want a quick, visual way to see what their application is about to send. The tool is not for production; it is a development aid. The README states it is 'a simple way to test your project's generated email during development.'

How It Works: SMTP Catch-All and Web GUI

MailDev runs two services: an SMTP server (default port 1025) and an HTTP web server (default port 1080). Your application sends email to the SMTP port, and MailDev stores each message. The web GUI then lists those messages, allowing you to view their content, headers, and attachments. The mechanism is straightforward: it accepts SMTP connections, parses the message, and stores it, either in memory or on disk if you set `--mail-directory`. The GUI reads from that store. The 3.0 rewrite re-structured the entire project, according to the README's note, but the core flow remains the same. The storage limit feature works by discarding the oldest `.eml` file and its attachments when `--max-emails` is reached, and it trims any backlog at startup.

Getting It Running: Commands and Configuration

Installation is a single npm command: `npm install -g maildev`. After that, you can run `maildev` with no arguments to start both servers on their default ports. For Docker, the README shows `docker run -p 1080:1080 -p 1025:1025 maildev/maildev`. Configuration is done via command-line flags or environment variables. For example, to change the SMTP port, use `-s, --smtp <port>` or set `MAILDEV_SMTP_PORT`. The web port is `-w, --web <port>` or `MAILDEV_WEB_PORT`. To persist emails across restarts, set `--mail-directory <path>`. To cap the store, use `--max-emails <count>`, with 0 meaning unlimited. There are also options for HTTPS (`--https`, `--https-key`, `--https-cert`), incoming SMTP authentication (`--incoming-user`, `--incoming-pass`), and outgoing relay via `--outgoing-host` and `--outgoing-port`. A configuration file can be passed with `--config <file>`. The README lists all these options in a table, so you can pick what you need.

Persistence and Storage Limits: What Changed in 3.0

One notable feature of the 3.0 rewrite is the explicit storage limit. By default, `--max-emails 0` keeps every email, preserving historical behavior. If you set a positive limit, the oldest email is discarded when a new one arrives, and its `.eml` file and attachments are removed. This keeps a persisted mail directory bounded. The README also says that any backlog left by earlier runs is trimmed to the same limit at startup. This is a practical improvement over the v2 behavior, where you had to manually clean up. However, the trimming logic is only as good as the limit you set; if you set it too low, you might lose emails you wanted to inspect. The persistence via `--mail-directory` is a real change, as v2 was primarily in-memory. This makes MailDev more useful for debugging sessions that span restarts.

Auto-Relay and MCP: Two Advanced Features

MailDev includes an auto-relay mode, enabled with `--auto-relay [email]`. This forwards incoming mail to a real SMTP server, configured via `--outgoing-host`, `--outgoing-port`, and related options. You can also pass filter rules with `--auto-relay-rules <file>` to control which messages get relayed. This is useful when you want to selectively send some test emails to a real inbox. More interestingly, the 3.0 release candidate adds an MCP server, enabled with `--mcp`. MCP stands for Model Context Protocol, and the README says it is for 'Claude integration.' This suggests you can use an AI assistant to inspect or manage emails through MailDev. The documentation is thin on specifics; it just lists the flag. If you do not use Claude or MCP, this feature is irrelevant, but it shows the project is moving toward AI-assisted development workflows.

Limitations and When It Is the Wrong Tool

MailDev is not a mail server for production. It has no delivery logic; it only catches and displays. The README warns that the 3.0 release candidate is a complete rewrite, so you may run into issues. The documentation even advises installing the latest v2 release if you encounter problems. That is a clear sign that 3.0 is not yet stable. Another limitation is the lack of a built-in way to send email from the GUI; you can only view what your application sends. If you need to test sending as well as receiving, you would need a different tool. The `--max-message-size` default is 52,428,800 bytes (50 MB), so very large messages are rejected by default. If you need to test messages larger than that, you must change the setting. Finally, the web GUI is basic; it does not offer advanced search or filtering beyond what the interface provides, which the README does not detail.

Alternatives: How MailDev Compares

The main alternative is MailHog, a similar SMTP catcher with a web UI. The difference is in the implementation and features. MailHog is written in Go, so it runs as a single binary without Node.js. MailDev requires Node.js, which is a dependency you might not want. MailHog also supports MongoDB or in-memory storage, while MailDev now offers file-based persistence via `--mail-directory`. MailHog has been around longer and may have a more stable API. Another alternative is to use a real mail server like Postfix in a test environment, but that requires more setup and does not provide a web GUI out of the box. For developers already in the Node.js ecosystem, MailDev is convenient because it is installed via npm. For those who want a zero-dependency binary, MailHog is the better choice. The choice comes down to your runtime preferences and whether you need the MCP integration that MailDev 3.0 offers.

Maintenance and License Considerations

MailDev is licensed under the MIT license, which means you can use, modify, and distribute it freely, including in commercial projects. The license does not impose copyleft obligations, so you do not have to share your own code. The project is actively maintained; the last push to the main branch was on 2026-08-28, and there are release candidates from 2026. However, the 3.0 release candidate is a rewrite, so the maintenance cost for you is higher during this transition. You will need to track changes between release candidates, as the API might shift. The v2.2.1 release from December 2024 is stable, but the project seems to be focusing on 3.0. If you adopt 3.0, expect to update your configuration as the project stabilizes. The documentation is clear about the storage limit behavior, but other features like MCP are under-documented, so you may need to read the source code to understand how they work.

Editorial conclusion

Adopt MailDev 3.0 if you are a developer who needs a local SMTP sink with a web GUI and you accept the risk of release-candidate instability. Do not use it for production mail handling or if you require a stable, long-term API; the 3.0 rewrite may change behavior. Before adopting, verify that the MCP server and auto-relay features work with your toolchain, and test the `--max-emails` trimming logic with your actual mail volume. If you need a battle-tested version, stick with v2.2.1 until 3.0 reaches a stable release.

Official sources

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