Skip to content
Get packs

Guide · Open source

How to use Mailpit: install, catch test emails and automate checks

Updated · written with AI from the project's own documentation and checked against our catalogue data

Mailpit is an open-source email testing tool for developers. It runs an SMTP server that captures the emails your application sends, so they never reach real inboxes, and shows them in a web interface where you can read, search and check them. This guide walks through installing it, sending a first test message, and using its REST API in automated tests.

Mailpitaxllent/mailpit · ★ 10.8k · MIT

Quick start

  1. 1Install Mailpit. Install the single binary with Homebrew on a Mac, or with the install script on Linux or Mac. Windows users can download the static binary from the releases page.
  2. 2Start Mailpit. Run mailpit so the web UI listens on port 8025 and the SMTP server on port 1025.
  3. 3Open the web UI. Visit http://0.0.0.0:8025 in your browser to see captured messages.
  4. 4Set your app's SMTP port. Configure your application to send mail to port 1025 instead of a real mail server.
  5. 5Trigger an email. Run a signup, password reset or notification in your app and watch it appear in the web UI.
  6. 6Automate checks. Use the REST API in your integration tests to look up captured messages and check their contents.

Install Mailpit on Mac, Linux or Windows

Mailpit runs as a single binary. On a Mac you can install it with Homebrew. Linux and Mac users can use the install script, which places the binary at /usr/local/bin/mailpit by default. Windows users can download a static binary from the releases page and run it as ./mailpit or copy it to their PATH.

Mailpit is also available for Arch Linux (AUR), FreeBSD, as Docker images and as source code to compile yourself. The README lists no prerequisites for installing it.

  • Mac with Homebrew: brew install mailpit
  • Linux or Mac with the install script, installing to /usr/local/bin/mailpit
  • Windows, Linux or Mac: download the static binary from the releases page
brew install mailpit

Start Mailpit and open the web interface

Run mailpit -h to see the available options. By default the web UI listens on http://0.0.0.0:8025 and the SMTP server listens on 0.0.0.0:1025. Open the web UI address in your browser to see captured messages as they arrive.

On a Mac installed with Homebrew, you can run brew services start mailpit to have it run automatically in the background.

  • Web UI: http://0.0.0.0:8025
  • SMTP server: 0.0.0.0:1025
mailpit -h

Point your application at Mailpit's SMTP server

Configure your application to send mail to the SMTP port Mailpit uses, which is 1025 by default. Your application keeps its normal sending code; only the SMTP host and port change. Once you trigger an action such as a signup, the message appears in the web UI instead of going to a real recipient.

If your application sends mail through sendmail, which is common in PHP, Mailpit can act as a substitute for sendmail. The README links to separate sendmail setup instructions in the documentation.

  • Set the SMTP host to localhost (or the host Mailpit runs on)
  • Set the SMTP port to 1025
  • Trigger a signup, password reset or notification and check the web UI

Search, read and check captured emails

The web UI lets you view messages in several formats: formatted HTML, highlighted HTML source, text, headers, raw source and MIME attachments, including image thumbnails. It has mail search for finding specific messages.

Mailpit also includes an HTML check that tests and scores mail client compatibility, a link check for message links and linked images, and a spam check that requires a running SpamAssassin server. Message tagging can be applied manually or automatically using filtering and plus addressing.

  • View formatted HTML, HTML source, text, headers, raw source and attachments
  • Search captured mail with the built-in search filters
  • Run HTML compatibility and link checks
  • Tag messages manually or with filters and plus addressing

Use the REST API in automated tests

Mailpit includes a REST API for integration testing. Your automated tests can send a request that triggers an email, then query Mailpit's API to confirm the message was captured and inspect its contents. The API documentation is linked from the project README.

Mailpit also offers a Chaos feature that enables configurable SMTP errors, which helps test how your application handles mail failures.

  • Trigger the email from your test
  • Query the REST API for captured messages
  • Assert on recipients, subject or body

Configure optional features

Mailpit supports optional HTTPS and authentication for the web UI, SMTP with STARTTLS or SSL/TLS, and an optional POP3 server so you can download captured messages into an email client. You can also enable SMTP relaying to release messages through another SMTP server, SMTP forwarding to send messages to predefined addresses, and a webhook for received messages.

Run mailpit -h and the documentation for the full list of runtime options before enabling these, since each one changes how Mailpit behaves.

  • HTTPS and authentication for the web UI
  • SMTP with STARTTLS or SSL/TLS, and an accept-any authentication mode
  • POP3 server, SMTP relaying, SMTP forwarding and webhooks

What people use it for

  • Checking that signup and password reset emails contain the right links and text before release
  • Writing integration tests that confirm a notification email was sent after an action
  • Testing how HTML emails look across clients using the built-in HTML check
  • Replacing MailHog with a maintained tool in an existing local development setup
  • Testing how an application handles SMTP errors using the Chaos feature

Frequently asked questions

Is Mailpit free and open source?

Yes. Mailpit is released under the MIT licence and its source code is on GitHub. The README also mentions Mailtrap as a separate commercial product for team features, which is not part of Mailpit.

How do I install Mailpit on a Mac?

Run brew install mailpit with Homebrew. To run it automatically in the background, use brew services start mailpit.

What port does Mailpit use for SMTP?

By default the SMTP server listens on 0.0.0.0:1025, and the web UI listens on http://0.0.0.0:8025. Point your application's SMTP settings at port 1025.

Can Mailpit send emails to real recipients?

No. Mailpit is an email test catcher, not a production mail server. Its SMTP relaying feature can release messages through another SMTP server, but the README does not describe full delivery queues or bounce handling.

Is Mailpit a replacement for MailHog?

The README says Mailpit was originally inspired by MailHog, which is no longer maintained. Mailpit is presented as a maintained alternative with a web UI, SMTP server and REST API.

Does Mailpit need any other software installed?

The README describes Mailpit as zero-dependency and runs it from a single static binary. It lists no prerequisites for installation. The spam check is the exception, since it needs a running SpamAssassin server.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Mailpit suits developers who need to see and test emails their application sends during local development, and teams that want to assert on email in automated integration tests. It is not suitable if you need to deliver mail to real recipients, need shared hosted inboxes or team features, or need a full mail transfer agent with delivery queues and bounce handling. For those, look at a production mail service or a hosted product such as Mailtrap.

Install options & downloads