Mailpit - email testing for developers

Website • Documentation • API

Mailpit is a small, fast, low memory, zero-dependency, multi-platform email testing tool & API for developers.

It acts as an SMTP server, provides a modern web interface to view & test captured emails, and includes an API for automated integration testing.

Note: This is a fork of Mailpit with additional bounce message functionality. The original Mailpit was inspired by MailHog which is no longer maintained.

• Runs entirely from a single static binary or multi-architecture Docker images
• Modern web UI with advanced mail search to view emails (formatted HTML, highlighted HTML source, text, headers, raw source, and MIME attachments including image thumbnails), including optional HTTPS & authentication
• SMTP server with optional STARTTLS or SSL/TLS, authentication (including an "accept any" mode)
• A REST API for integration testing
• Real-time web UI updates using web sockets for new mail & optional browser notifications when new mail is received
• Optional POP3 server to download captured message directly into your email client
• HTML check to test & score mail client compatibility with HTML emails
• Link check to test message links (HTML & text) & linked images
• Spam check to test message "spamminess" using a running SpamAssassin server
• Create screenshots of HTML messages via web UI
• Mobile and tablet HTML preview toggle in desktop mode
• Message tagging including manual tagging or automated tagging using filtering and "plus addressing"
• SMTP relaying (message release) - relay messages via a different SMTP server including an optional allowlist of accepted recipients
• SMTP forwarding - automatically forward messages via a different SMTP server to predefined email addresses
• Message bouncing - generate and send Delivery Status Notification (DSN) bounce messages via a configured SMTP relay server with customizable bounce reasons and SMTP status codes
• Fast message storing & processing - ingesting 100-200 emails per second over SMTP depending on CPU, network speed & email size, easily handling tens of thousands of emails, with automatic email pruning (by default keeping the most recent 500 emails)
• Chaos feature to enable configurable SMTP errors to test application resilience
• List-Unsubscribe syntax validation
• Optional webhook for received messages

The Mailpit web UI listens by default on http://0.0.0.0:8025 and the SMTP port on 0.0.0.0:1025.

Mailpit runs as a single binary and can be installed in different ways:

• Mac: brew install mailpit (to run automatically in the background: brew services start mailpit)
• Arch Linux: available in the AUR as mailpit
• FreeBSD: pkg install mailpit

Linux & Mac users can install it directly to /usr/local/bin/mailpit with:

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

You can also change the install path to something else by setting the INSTALL_PATH environment, for example:

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

Static binaries can always be found on the releases. The mailpit binary can be extracted and copied to your $PATH, or simply run as ./mailpit.

See Docker instructions for 386, amd64 & arm64 images.

To build Mailpit from source, see Building from source.

Run mailpit -h to see options. More information can be seen in the docs.

If installed using homebrew, you may run brew services start mailpit to always run mailpit automatically.

Mailpit can generate and send Delivery Status Notification (DSN) bounce messages via a configured SMTP relay server. This is useful for testing how your application handles bounced emails.

By default, bounce messages are sent back to the same Mailpit instance on 127.0.0.1:1025, creating a complete testing loop. You can configure a different SMTP server using the following environment variables:

• MP_BOUNCE_RELAY_ADDR - SMTP server address for sending bounce messages (defaults to 127.0.0.1)
• MP_BOUNCE_RELAY_PORT - SMTP port (defaults to 1025 to match Mailpit's SMTP port)
• MP_BOUNCE_RELAY_STARTTLS - Enable STARTTLS (set to 1 or true)
• MP_BOUNCE_RELAY_TLS - Enable TLS (set to 1 or true)
• MP_BOUNCE_RELAY_ALLOW_INSECURE - Allow insecure TLS connections (set to 1 or true)
• MP_BOUNCE_RELAY_AUTH - Authentication method: plain, login, or cram-md5
• MP_BOUNCE_RELAY_USER - Username for authentication
• MP_BOUNCE_RELAY_PASS - Password for authentication
• MP_BOUNCE_RELAY_SECRET - Secret for CRAM-MD5 authentication
• MP_BOUNCE_FROM - From address for bounce messages (email header, e.g., Mail Delivery Subsystem <MAILER-DAEMON@example.com>)
• MP_BOUNCE_MAILFROM - MAIL FROM address for bounce messages (SMTP envelope sender, defaults to email address extracted from MP_BOUNCE_FROM if not set)

Example configuration:

export MP_BOUNCE_RELAY_ADDR="smtp.example.com"
export MP_BOUNCE_RELAY_PORT="587"
export MP_BOUNCE_RELAY_STARTTLS="1"
export MP_BOUNCE_RELAY_AUTH="plain"
export MP_BOUNCE_RELAY_USER="bounce@example.com"
export MP_BOUNCE_RELAY_PASS="password"
export MP_BOUNCE_FROM="Mail Delivery Subsystem <MAILER-DAEMON@example.com>"

Once configured, you can use the bounce feature from the web UI by clicking the "Bounce" button next to any message and selecting a bounce reason (e.g., "Mailbox Not Found", "Mailbox Full", etc.).

Please refer to the documentation on how to easily test email delivery to Mailpit.

Mailpit's SMTP server (default on port 1025), so you will likely need to configure your sending application to deliver mail via that port. A common MTA (Mail Transfer Agent) that delivers system emails to an SMTP server is sendmail, used by many applications, including PHP. Mailpit can also act as substitute for sendmail. For instructions on how to set this up, please refer to the sendmail documentation.

For team features, multiple inboxes, and a hosted setup, try Mailtrap, our friendly companion.