Mailpit: an SMTP sink and REST API for testing email in development

What Mailpit replaces in a developer's inbox

Mailpit is an SMTP server that does not deliver mail. Applications point their outgoing mail configuration at it, messages are captured, and the developer reads them in a web interface or through an API. The README describes it as an email testing tool and API that acts as an SMTP server and provides a web interface plus an API for automated integration testing.

The audience is narrow but common: backend developers working on signup flows, password resets, notification digests, or anything else that sends mail. The alternative is either a real mailbox that fills with test messages, or a hosted service that receives them for you. Mailpit takes the first problem away by keeping everything local, and it takes the second away by not requiring an account. It also ships a POP3 server as an optional component, so a desktop mail client can pull captured messages directly.

The project states it was inspired by MailHog, which the README says is no longer maintained and has not seen active development or security updates for a few years. That lineage matters when you are choosing: Mailpit is the migration target for teams still running MailHog, and the README treats that as the origin story rather than a comparison point.

One Go binary, an embedded UI and a SQLite store

The repository layout shows a Go program (main.go, cmd/, internal/, server/) with a Vue front end under server/ui-src that is bundled by esbuild via esbuild.config.mjs. The Dockerfile builds the UI with npm, then compiles a static Go binary with CGO_ENABLED=0, and the final image is Alpine with the binary copied in and tzdata added. The image declares EXPOSE 1025/tcp, 1110/tcp and 8025/tcp, and the healthcheck runs /mailpit readyz, which tells you the binary itself exposes a readiness command rather than relying on an HTTP probe.

Storage is SQLite: go.mod lists modernc.org/sqlite, a pure-Go driver, which is consistent with the zero-dependency, CGO-free build. The README says message storage and processing ingest 200-300 emails per second over SMTP depending on CPU, network speed and email size, that it handles tens of thousands of emails, and that pruning by volume or age keeps the most recent 500 emails by default. Those are the project's own figures, not measurements I made.

The web UI updates in real time over web sockets (gorilla/websocket is in go.mod), with optional browser notifications. Messages can be tagged manually or automatically through filtering and plus addressing. The SMTP side supports STARTTLS or SSL/TLS and authentication, including what the README calls an accept-any mode, which is convenient locally and obviously not something to expose.

Installing Mailpit and sending the first message

The install options in the README are package managers, an install script, static binaries from the releases page, Docker, or building from source. On macOS, brew is the shortest path, and brew services can keep it running in the background.

brew install mailpit
brew services start mailpit

On Linux and macOS the install script places the binary at /usr/local/bin/mailpit by default, and the path can be overridden with the INSTALL_PATH environment variable.

sudo sh < <(curl -sL https://raw.githubusercontent.com/axllent/mailpit/develop/install.sh)

Windows users are pointed at the static binaries on the releases page; the README says the mailpit binary can be extracted and copied to your $PATH, or run as ./mailpit. The README does not describe a Windows package manager install.

Once it is running, the web UI listens on http://0.0.0.0:8025 and the SMTP server on 0.0.0.0:1025 by default. A first real use is to send a message with a client that lets you set the SMTP host and port. The README's own testing pointer is the documentation page on testing email delivery, and for sendmail configuration it notes that you will likely need to point your sending application at port 1025. After sending, the message should appear in the UI at port 8025 without a refresh, because the interface updates over web sockets.

For Docker, the README defers to the Docker documentation page for the 386, amd64 and arm64 images rather than listing a run command in the README itself. The Dockerfile shows the three exposed ports (1025, 1110, 8025), which is the useful detail when you write your own run command.

The REST API is the part that belongs in CI

The README lists a REST API for integration testing and links to a v1 API reference. That is the difference between Mailpit and a plain SMTP debug server: a test can send a message through the application under test, then query Mailpit to assert that the message arrived, who it was addressed to, and what the body contains, without parsing a mailbox file or scraping a UI. The API reference is the source to read for endpoint names and payloads; the README does not enumerate them.

Two features are relevant to test suites that care about behaviour under failure. The chaos feature enables configurable SMTP errors so you can check how your application reacts when the mail server rejects or fails a message. SMTP relaying, which the README calls message release, forwards a captured message through a different SMTP server, optionally restricted by an allowlist of accepted recipients. SMTP forwarding does something similar automatically, sending messages to predefined addresses through another SMTP server. The distinction is manual versus automatic, and the allowlist is the safety mechanism worth configuring before any relay points at a real mail server.

There is also a webhook for received messages, which is another way to drive a test or a local script from the arrival of mail.

Where Mailpit is the wrong tool

Mailpit captures mail; it does not tell you whether that mail would reach an inbox. The HTML check scores compatibility with mail clients using data the package.json script refreshes from caniemail.com, and the link check tests links and linked images in the message. Both are static analysis of the message. The spam check requires a running SpamAssassin server, which is a separate piece of infrastructure you have to operate, and the README does not claim it works without one.

The second limitation is retention. The default keeps the most recent 500 emails and prunes by volume or age. A long-running shared instance will silently discard older messages, so a test that expects yesterday's message to still be there will fail for reasons unrelated to your code. That is a configuration decision, but the default is aggressive for anything beyond a single developer's machine.

The third is exposure. Accept-any SMTP authentication, an open SMTP port and a web UI with optional authentication add up to a service that should not be reachable from the public internet. The README presents HTTPS and authentication as optional configuration for the HTTP side, which is the right framing for a local tool and the wrong one for a shared host. Finally, if your goal is to test deliverability, inbox placement or DMARC alignment against real providers, this is not that product and no amount of configuration makes it one.

Mailpit against MailHog and hosted capture services

The README names MailHog as the inspiration and states that MailHog is no longer maintained and has not seen active development or security updates for a few years. The practical difference for a team still on MailHog is maintenance rather than features: Mailpit is a Go project with releases in 2026, a Docker image, and a healthcheck, while MailHog's own issue thread is cited by the README as the reason to move. If your tooling already speaks MailHog's SMTP port, the migration is mostly a configuration change plus a check of which API your tests call, because the API surfaces are not identical.

The other comparison is hosted capture services such as Mailtrap. The difference is architectural, not cosmetic. A hosted service receives your test mail on its infrastructure, so the messages leave your machine and you get a shared, remote view, which suits teams that want one place to look and are comfortable with mail content leaving the network. Mailpit runs locally as a single binary with embedded storage, so nothing leaves the machine and there is no account or quota, but there is also no shared inbox unless you run an instance somewhere and expose it, at which point the exposure concerns above apply. Neither approach validates real deliverability. Pick hosted capture when you need a shared, remote mailbox and accept the data path; pick Mailpit when you want the sink, the API and the storage on your own machine.

Maintenance, licence and what upgrading costs

The repository is not archived, and the last push was on 2026-09-20. Releases are frequent and small: v1.31.0 on 2026-08-22, v1.31.1 on 2026-09-05, v1.31.2 on 2026-09-19. The CHANGELOG.md at the repository root is the file to read before upgrading, since the README does not document rollback or downgrade steps.

Upgrade cost depends on how you installed it. A Homebrew or package-manager install is a package upgrade; the install script pulls the current binary from the develop branch; Docker users pull a new image tag. The one thing to watch is the API, because integration tests depend on it. The README links a v1 API reference, and the version prefix is the signal that the API is versioned rather than free to change silently. If you pin a Docker tag, check the CHANGELOG between your tag and the target before moving.

The licence is MIT, which the Dockerfile also sets as the image's org.opencontainers.image.licenses label. MIT is permissive: it allows commercial use and modification with the copyright notice and permission notice retained. The Dockerfile additionally generates a third-party licence report into internal/licenses/third-party.txt during the build, which is a useful artifact if you redistribute the binary and need to account for bundled dependencies. That is a factual observation about the build, not legal advice; your own counsel should review redistribution questions.

Editorial conclusion

Adopt Mailpit if you want a local SMTP sink with a web UI and an API that your integration tests can call, and if a single static binary or the multi-architecture Docker image fits your workflow. Do not adopt it if you need real deliverability data: it captures messages, it does not send them to inboxes, and the spam and link checks depend on external services or on the message content itself. Before wiring it into CI, verify the port and storage settings you intend to use (SMTP defaults to 1025, the UI to 8025, and the default retention keeps the most recent 500 emails), and confirm which API endpoints your test suite actually calls.

Frequently asked questions

Official sources

1. axllent/mailpit on GitHub
2. License: MIT
3. Project website
4. README
5. Releases