MailDev: an SMTP sink and web inbox for development email

The problem MailDev removes from the development loop

Any application that sends email needs someone to read that email. In development the recipient address is usually fake, the SMTP credentials point at a sandbox, and the person checking the output is the developer who just wrote the template. MailDev replaces the outbound trip with a local SMTP server that accepts everything and a web interface that lists what arrived. The README describes it as "a simple way to test your project's generated email during development", and the mechanism matches that description: you point your app's SMTP host at localhost, and the mail stops there. The audience is narrow and clear. Backend developers working on signup flows, password resets, invoices and notification templates. QA engineers who need to confirm a message was actually generated rather than mocked away. Anyone running an integration test suite that asserts on email content, since the SMTP port is a real socket and the messages are real RFC 5322 documents. It is not aimed at deliverability testing, inbox placement, or anything involving a real recipient.

How the SMTP catcher and web GUI fit together

The repository is a pnpm workspace with a turbo build, and the Dockerfile names the packages it compiles: core, smtp, api, mcp and cli, with the UI built by Vite. That layout tells you the shape of the system. An SMTP listener accepts connections on port 1025 by default. A separate HTTP service serves the web interface on port 1080 by default, and the same service exposes the API the interface calls. Mail is held in memory unless you give it a directory to persist into. The two ports are independent, which is why the Docker run command publishes both. The CLI exposes them separately too: --smtp and --web set the ports, --ip and --web-ip set the bind addresses, and the defaults differ, with SMTP binding to :: and the web service to 0.0.0.0. The README also lists an --mcp flag that enables an MCP server for Claude integration, which is a newer addition and one of the places where the 3.0 line diverges from what most published tutorials describe.

Installing MailDev and sending your first message

The README gives two install paths. The npm route installs the CLI globally, which puts a maildev binary on your PATH. The Docker route needs no Node.js at all and is the one most CI setups use, since it pins the environment to an image rather than a local runtime.

npm install -g maildev

Once installed, running maildev with no arguments starts the SMTP server on 1025 and the web interface on 1080. Open http://localhost:1080 in a browser and you should see an empty inbox. Nothing is configured yet, so no mail will appear until something sends to the SMTP port.

maildev --smtp 1025 --web 1080

The Docker equivalent publishes the same two ports from the maildev/maildev image on Docker Hub. The README shows this exact command, and the docs directory contains a longer guide for Docker usage.

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

With the server running, point your application's SMTP settings at localhost on port 1025. Send a test message through your application and the web interface should list it within a second or two. If you want mail to survive a restart, pass --mail-directory with a path; without it, the store is in memory and a restart clears the inbox.

Storage limits, persistence and the failure mode they create

MailDev keeps every email by default. The README states that --max-emails 0 means unlimited, and explains why: preservation of historical behaviour and durable persisted mail across restarts. That default is the first thing to think about. A development machine that runs for weeks, or a shared staging instance, accumulates mail indefinitely unless you cap it. Setting a positive limit changes the behaviour in a way worth reading carefully. When a new email arrives and the limit is reached, the oldest message is discarded along with its .eml file and its attachments, so a persisted mail directory stays bounded. The README also notes that any backlog left in the mail directory by earlier runs is trimmed to the same limit at startup. The practical consequence is that a test which depends on an old message still being present can fail after unrelated traffic arrives. If your suite asserts on a message from ten minutes ago, a low --max-emails value will silently delete it. The second limit is message size. --max-message-size defaults to 52428800 bytes, and the README says larger messages are rejected rather than truncated. A test that attaches a large fixture will fail at the SMTP layer, not in the UI, which makes the error easy to misread.

Auth, relaying and the options that move MailDev toward a real server

The CLI has a long tail of options that turn MailDev from a sink into something closer to a mail server, and this is where the project's scope gets blurry. --incoming-user and --incoming-pass add SMTP authentication for incoming mail, with --incoming-secure and certificate paths for TLS. --web-user and --web-pass put HTTP basic auth in front of the GUI. The outgoing family, --outgoing-host, --outgoing-port, --outgoing-user, --outgoing-pass and --outgoing-secure, configures a relay. --auto-relay with an optional address, plus --auto-relay-rules for filter rules, makes MailDev forward mail onward automatically. Each of these is a real feature, and together they describe a tool that can sit between an application and a real SMTP provider. That is also the case where MailDev is the wrong tool. If you enable auto-relay against a production provider, you are running development software in the delivery path, with no queue management and no bounce handling described in the README. The safer reading is that these options exist for staging environments where someone wants to inspect a subset of traffic, not for production delivery. --disable-web and --hide-extensions exist for the opposite reason: to strip the interface and control which SMTP extensions the server advertises, which matters when you are testing how a client behaves against a server that does not support a given extension.

MailDev versus Mailpit and MailHog

The package keywords list mailcatcher alongside maildev, and the search data around this project is full of comparison queries against Mailpit and MailHog. The honest difference is in the implementation and the packaging. MailDev is a Node.js and TypeScript project, distributed as an npm package and a Docker image, and its 3.0 line is a monorepo with separate core, smtp, api, mcp and cli packages. MailHog is a Go binary, which means a single static executable with no runtime dependency, and its development has been quiet for years. Mailpit is also Go, and it has become the common replacement recommendation because it bundles a similar SMTP catcher and web UI while continuing to receive updates. If your constraint is "no Node.js on the build agent", the Go tools win on deployment simplicity. If your constraint is "we already run Node.js and want the catcher as a dev dependency", MailDev fits without adding a second toolchain. The feature sets overlap heavily, so the deciding factor is usually which one your team can debug at 2am, not which one has more options. The one thing MailDev's README describes that the others do not is the --mcp flag for Claude integration, which is a genuine differentiator if you are wiring an agent into a local mail flow.

Release candidate status, licensing and upgrade cost

The README carries an explicit warning: the 3.0 release candidate has been released and includes a complete re-write and re-structuring of the entire project, and readers who hit issues are told to install the latest v2 release from the v2 branch. That is an unusually direct statement from a project about its own stability, and it should drive your version choice. The most recent release is [email protected], published on 2026-08-28, preceded by 3.0.0-rc.1 on 2026-07-06. The last stable release in the list is v2.2.1 from 2024-12-12, and it lives on a separate branch. So the upgrade path from v2 to v3 is not a patch bump. The monorepo split, the turbo build and the package restructuring mean the CLI surface is similar but the internals are not, and the README's own advice is to fall back to v2 when something breaks. The last push to the default branch was on 2026-08-28, so the repository is being worked on, but a release candidate is still a release candidate. On licensing, the project is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are included. That is the standard MIT obligation, and it applies to the Docker image as well as the npm package. If you vendor the source, keep the LICENSE file. This is a description of the licence text, not legal advice, and anything involving redistribution inside a commercial product should go past whoever handles that for your organisation.

Editorial conclusion

Adopt MailDev if you need a local SMTP endpoint and a browser inbox for development email, and you are comfortable running either the v2 line or the 3.0 release candidate. Do not adopt it as a production mail server or as a relay for real customer traffic. Before rolling it out, verify which release you are installing, check whether --max-emails is set for your persisted mail directory, and confirm the port bindings match your container network.

Frequently asked questions

Official sources

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