Mailpit is an alternative to MailHog. It is a hosted SMTP server. Instead of sending emails to recipients, it captures and stores all emails for inspection via web UI. This is useful for testing applications in staging and development environments.

Approach

Mailpit provides a shell script for installation. It just downloads the latest binary and copies it to /usr/local/bin/mailpit. It lacks configurations for Systemd and Apache web server. If you prefer docker, there are instructions for that. I prefer a manual setup, which involves building from source.

Prerequisites

Make sure the following software is installed:

• CentOS 9 (it should work on versions 7 and 8)

• Node.js

• Go

• Apache Web Server

• mod_proxy and mod_http Apache modules

Building

TIP: You can skip this step if you use the shell script for installation.

The application is developed in Go and npm is also required to build the web UI. Checkout out the source code from https://github.com/axllent/mailpit.git and navigate to the root folder of the source code.

npm install
npm run build
go build -ldflags "-s -w"
sudo cp ./mailpit /usr/local/bin/

Create Password File

The web UI and API uses Basic Authentication, but it is optional. SMTP authentication is also optional. I recommend enabling authentication for both web and SMTP access. Credentials are generated using htpasswd and stored in a file in any location. Web and SMTP can use separate credential files. For simplicity, I will use the same file for both.

sudo mkdir -p /etc/mailpit/htpasswd
sudo htpasswd -c /etc/mailpit/htpasswd bob123
sudo chmod 600 /etc/mailpit/htpasswd

NOTE: Whenever there are changes to the credential file, the Mailpit server must be restarted for the change to take effect.

Create Systemd Service File

Create a Systemd service file, /etc/systemd/system/mailpit.service.

[Unit]
Description=Email testing tool
Documentation=https://github.com/axllent/mailpit
After=network.target

; Support auto restart, required version >= 230. Ref: https://bit.ly/2YJ36hQ
;StartLimitIntervalSec=500
;StartLimitBurst=5

[Service]
Type=simple
; Files in /tmp/ will be auto deleted after 10 days. Ref: https://bit.ly/3q9bGpP
ExecStart=/usr/local/bin/mailpit --ui-auth-file /etc/mailpit/htpasswd --smtp-auth-file /etc/mailpit/htpasswd --smtp-auth-allow-insecure --db-file /tmp/mailpit.db

; Support auto restart. Ref: https://bit.ly/2YJ36hQ
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

NOTE: Emails are stored in an SQLite file. As specified in /usr/lib/tmpfiles.d/tmp.conf, files in /tmp/ will be deleted every 10 days. If you want to keep the database persistent, you may consider storing it in other places, e.g. /var/lib/mailpit/.

Enable and start the service.

sudo systemctl enable mailpit
sudo systemctl start mailpit

The web UI will be available at http://127.0.0.1:8025 (not accessible from the public). SMTP service will be available at 0.0.0.0:1025.

Reverse Proxy On Apache Web Server

Create a config file at /etc/httpd/conf.d/mailpit.example.com.conf.

<VirtualHost *:80>
    ServerName mailpit.example.com

    ProxyPass / http://localhost:8025/
    ProxyPassReverse / http://localhost:8025/

    CustomLog logs/mailpit.example.com-access.log combined
    ErrorLog logs/mailpit.example.com-error.log
</VirtualHost>

ServerName directive is not required if this is the only site hosted on the server. It is needed if the server is hosting multiple sites with different domain names. SSL is recommended (extra configuration is needed).

Restart the Apache web server.

sudo systemctl reload httpd

Usage

Set the SMTP configuration in your application with the following information:

• Host: <domain name of IP of server>

• Port: 1025

• Username: <defined in /etc/mailpit/htpasswd>

• Password: <defined in /etc/mailpit/htpasswd>