Mailpit

Last reviewed Aug 26, 2026 · 832 words

Mailpit is two ports and one binary. Anything that speaks SMTP to port 1025 gets captured instead of delivered, and you read it on port 8025 in a web interface that renders the HTML, checks the links and grades the spam score. It uses about 64 MB, needs no configuration to be useful, and is the MIT-licensed successor to MailHog that most Docker development stacks have quietly switched to since 2022. Nothing it receives ever reaches a real inbox, which is the whole point and also the trap.

Two ports, zero required config

services:
  mailpit:
    image: axllent/mailpit:latest
    ports:
      - "8025:8025"
      - "1025:1025"
    environment:
      MP_MAX_MESSAGES: 5000
      MP_DATABASE: /data/mailpit.db
      MP_SMTP_AUTH_ACCEPT_ANY: 1
      MP_SMTP_AUTH_ALLOW_INSECURE: 1
    volumes:
      - ./data:/data
    restart: unless-stopped

The two auth variables make it accept any username and password over plain SMTP, which is what you want, because half the applications you test refuse to send without credentials. MP_DATABASE persists messages across restarts; without it everything lives in memory and vanishes when the container does. The default cap is 500 stored messages, rolling; raise it if you are debugging a batch job. On the application side the settings are always the same: host mailpit, port 1025, no TLS, any user.

The homelab use nobody writes down

Developers use Mailpit to preview transactional email from the app they are writing. Self-hosters have a second use that is at least as valuable: a single inbox for every service's notifications during setup. Point Vaultwarden, Nextcloud, Gitea, Grafana and the rest at Mailpit, and you can verify that invitations, password resets and alert emails actually render and contain the right links before you wire in a real relay and find out from a user. It also swallows the deluge of "backup finished" mail that every service wants to send while you are still tuning it.

The trap is leaving it there. A Mailpit that is still the SMTP host six months later means the password-reset email your partner needed at 23:00 went into a jar on a server they cannot see. Treat it as scaffolding, and keep a list of which services still point at it.

Release a message when you need it delivered

There is a middle path for the cases where most mail should be trapped but one message must go out. Give Mailpit a relay configuration file and the interface grows a "Release" button that forwards a single captured message through a real SMTP server:

# relay.yml, mounted and referenced via MP_SMTP_RELAY_CONFIG=/data/relay.yml
host: smtp.example.com
port: 587
username: [email protected]
password: change-me
starttls: true

Set only that, not the relay-everything option, unless you specifically want Mailpit acting as a store-and-forward proxy, which is a job it will do but was not built for. For real outbound mail from a homelab, the honest advice in the email category still applies: a transactional provider for sending, and a proper server such as Stalwart only if you truly want to host mailboxes.

The checks are the reason to pick it over MailHog

MailHog did the capture job well and has not seen meaningful development in years. Mailpit adds the things you actually need when debugging templates: an HTML compatibility check that scores your markup against what mail clients support, a link checker that follows every URL in the message and reports the status codes, optional SpamAssassin scoring if you point it at a SpamAssassin daemon, and preview widths for phone and tablet. Tagging and search work across thousands of messages, and the REST API at /api/v1/messages lets a test suite assert that an email was sent, inspect its body and wipe the inbox between runs. It is also a full-featured tool in the dev-tools category sense: fast, small, single binary, no database server.

It is not a mail server, and it is not webmail

Mailpit delivers nothing and stores nothing you would want to keep. It is not an MTA, not an IMAP server, and not a webmail client for reading your real mailbox; SnappyMail and Roundcube are that kind of tool and connect to real IMAP accounts, which Mailpit has no concept of. The catalogue's two cons say the same thing twice: for testing, not production, and not a real mail server. Both are features when you read them right.

What I'd do

Run Mailpit as a permanent container on the homelab with MP_DATABASE set and 5,000 messages retained, and point every new service at it for its first week. Once the notifications look right, switch that service to the real provider and cross it off the list. Keep the relay file configured so the odd trapped message can be released rather than re-triggered. In a project's docker-compose.yml for development it goes in unconditionally, on 64 MB, with no reason to ever reach for MailHog again.