Mailpit: A Self-Hosted Mailtrap Alternative for Email Testing

If you frequently develop features that involve sending emails—such as password resets, notifications, invoices, and more—you are probably familiar with Mailtrap. It is an incredibly useful tool because it intercepts emails sent from your application without actually delivering them to real mailboxes, allowing you to safely inspect them during development.

However, Mailtrap’s free plan has limitations (email volume, number of inboxes, retention, etc.). If you need a similar tool but want it self-hosted, completely free, and running entirely on your own local machine or staging server, Mailpit is an excellent alternative.

What is Mailpit?#

Mailpit is an open-source, lightweight, and fast email testing tool with minimal dependencies. Conceptually, Mailpit plays two roles at once:

SMTP Server — Your application sends emails to Mailpit just like it would to a real SMTP provider, and Mailpit intercepts them.
Web UI & API — You can view intercepted emails through a modern web dashboard (supporting HTML, plain text, headers, raw source, and attachments) or fetch them via an API for automated testing.

Since it runs as a single binary or a Docker image and doesn’t require an external database, Mailpit is extremely easy to run in local development or staging environments.

Why Choose Mailpit as a Mailtrap Alternative?#

Feature	Mailtrap	Mailpit
Hosting	Cloud (SaaS)	Self-hosted (Docker)
Cost	Free with limits, paid for more	Free, limited only by your server resources
Data Privacy	Stored on third-party servers	Stored on your own server or volume
Setup	Sign up, create inbox, get credentials	`docker compose up` and it runs
Authentication	Built-in / Required	Configurable (explained below)

For development and internal staging needs, Mailpit is a perfect fit because it gives you full control over your data without any subscription costs.

Docker Compose Setup#

Here is the docker-compose.yml configuration. It includes login protection for the Web UI and SMTP authentication (replicating Mailtrap’s requirement for credentials):

1
services:
2
  mailpit:
3
    image: ghcr.io/axllent/mailpit:v1.30.1@sha256:f35e6c915ecec9c0bb1837ee176554c695f4558eda25a6d82c1d30ba2145f769
4
    container_name: mailpit
5
    restart: unless-stopped
6
    volumes:
7
      - ./data:/data
8
      # Mount credentials file to protect UI and SMTP
9
      - ./auth.txt:/auth.txt:ro
10
    ports:
11
      - "8025:8025" # Web UI Dashboard
12
      - "1025:1025" # SMTP Port
13
    environment:
14
      MP_MAX_MESSAGES: 5000
15
      MP_DATABASE: /data/mailpit.db
16

17
      # 1. Lock the Web UI Dashboard (requires login like Mailtrap)
18
      MP_UI_AUTH_FILE: /auth.txt
19

20
      # 2. Require valid SMTP authentication from the auth file
21
      MP_SMTP_AUTH_FILE: /auth.txt
22

23
      # MP_SMTP_AUTH_ACCEPT_ANY: 1  # <-- Disable to enforce strict authentication
24

25
      # Allow plain-text login from the application (for internal network without SSL/TLS)
26
      MP_SMTP_AUTH_ALLOW_INSECURE: 1

Environment Variables Breakdown#

MP_MAX_MESSAGES — The maximum number of emails stored before older ones are automatically pruned.
MP_DATABASE — The path to the SQLite database file where Mailpit stores emails.
MP_UI_AUTH_FILE — Enables Basic Auth on the Web UI, pointing to the credentials file.
MP_SMTP_AUTH_FILE — Requires applications to authenticate with a valid username/password, pointing to the same credentials file.
MP_SMTP_AUTH_ALLOW_INSECURE — Allows SMTP authentication over plain-text (non-TLS) connections. This is suitable for internal testing environments, but should be avoided if Mailpit is exposed to the public internet.

Note: If you want SMTP authentication enabled but don’t care about validation (e.g., local development where any credentials should work), you can set MP_SMTP_AUTH_ACCEPT_ANY: 1 instead. Mailpit will then accept any username and password combination.

Generating the Authentication File (`auth.txt`)#

This is where people often run into issues. Mailpit does not read plain-text passwords directly from the auth.txt file. Instead, the passwords must be hashed (Mailpit supports formats like bcrypt, commonly used in standard htpasswd files).

The most practical way to generate this is using the htpasswd utility from the apache2-utils package (Debian/Ubuntu) or httpd-tools (RHEL/CentOS).

1. Install `htpasswd` (if not already installed)#

1
# Ubuntu/Debian
2
sudo apt install apache2-utils
3

4
# RHEL/CentOS/Fedora
5
sudo dnf install httpd-tools

2. Generate the Credentials#

Create a new auth.txt file with your first user using the -c (create) and -B (bcrypt) flags:

1
htpasswd -B -c auth.txt test@mailer.com

You will be prompted to enter and confirm a password:

1
New password:
2
Re-type new password:
3
Adding password for user test@mailer.com

If you want to add additional users (e.g., for team members), run the command again without the -c flag so you don’t overwrite the existing file:

1
htpasswd -B auth.txt dev2@mailer.com

The resulting auth.txt file will look like this:

1
test@mailer.com:$2y$05$examplehashedpasswordstringxxxxxxxxxxxxxxxxxxxxxx
2
dev2@mailer.com:$2y$05$anotherexamplehashxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Save this file in the same directory as your docker-compose.yml, then start the container:

1
docker compose up -d

3. Using the Credentials#

Log in to the Web UI at http://localhost:8025 using test@mailer.com and the password you created.
Configure SMTP in your application (e.g., in Laravel .env, Node.js, etc.):

1
MAIL_HOST=localhost
2
MAIL_PORT=1025
3
MAIL_USERNAME=test@mailer.com
4
MAIL_PASSWORD=your_configured_password
5
MAIL_ENCRYPTION=null

Since we enabled MP_SMTP_AUTH_ALLOW_INSECURE=1, the application can authenticate without TLS, which is perfect for local or testing setups.

Conclusion#

With this setup, you now have a fully functional email testing environment running on your own infrastructure. It is secure, limit-free, and costs nothing. For small teams or personal projects, Mailpit is a incredibly solid replacement for Mailtrap.

If you plan to expose Mailpit to the public internet, make sure to add a reverse proxy with HTTPS (such as Nginx or Caddy) in front of port 8025, and avoid using MP_SMTP_AUTH_ALLOW_INSECURE in non-isolated networks.