Operating System CentOS

How to Install MailCatcher (or Mailpit) on AlmaLinux 9 and Rocky Linux 9

Install MailCatcher with Ruby 3.3 on the RHEL 9 family, run it as a service, and see when the single-binary Mailpit is the easier choice.

MailCatcher is a small SMTP server for development and staging: your application sends mail to it, nothing is delivered to real recipients, and every message shows up in a web interface. This guide installs MailCatcher on AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9, runs it as a systemd service, and then shows Mailpit, a maintained single-binary tool that does the same job without a Ruby toolchain.

CentOS 7 reached end of life in June 2024, and the Ruby it shipped is far too old for current MailCatcher releases. On the RHEL 9 family the default Ruby is 3.0, which is also too old: MailCatcher now requires Ruby 3.3 or newer, so you need the Ruby 3.3 module stream.

Which tool should you install?

MailCatcherMailpit
InstallationRuby gem with native extensions (needs a compiler)One static binary
SMTP port10251025
Web interface port10808025
Default listen address127.0.0.10.0.0.0 (all interfaces)
StorageIn memory, lost on restartTemporary file by default, or a database file you choose

If your team already uses MailCatcher or your tooling expects port 1080, install MailCatcher. For a new setup, Mailpit is quicker to install and easier to keep updated. Both accept mail on port 1025, so an application configured for one works with the other.

Requirements

  • AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9 with a sudo user.
  • A development or staging server. Neither tool authenticates SMTP clients by default, and captured messages often contain password-reset links and personal data, so do not expose the ports to the internet.

Option 1: Install MailCatcher

Install Ruby 3.3 and build tools

List the Ruby streams your release offers, then switch to 3.3:

sudo dnf module list ruby
sudo dnf module reset -y ruby
sudo dnf module enable -y ruby:3.3

Install Ruby, its headers and the compiler packages that MailCatcher's native extensions need:

sudo dnf install -y ruby ruby-devel gcc gcc-c++ make redhat-rpm-config sqlite-devel openssl-devel

Confirm the version is 3.3 or later:

ruby --version

Install the gem

sudo gem install mailcatcher

Install MailCatcher system-wide like this rather than adding it to your application's Gemfile; the project advises against bundling it because its dependencies will eventually conflict with your application's.

Find out where the executable was placed, since the service file needs the full path:

command -v mailcatcher
mailcatcher --version

Run MailCatcher

Started without options, MailCatcher goes to the background and listens on localhost only:

mailcatcher

It prints the two addresses, smtp://127.0.0.1:1025 and http://127.0.0.1:1080. The options you are most likely to need:

OptionEffect
--ip IPListen address for both the SMTP and the web server
--smtp-ip, --smtp-portAddress and port of the SMTP server only
--http-ip, --http-portAddress and port of the web interface only
--messages-limit COUNTKeep only the most recent messages
--no-quitRemove the Quit button from the web interface
-f, --foregroundStay in the foreground (use this under systemd)

Run MailCatcher as a service

Create a dedicated account and a unit file. Adjust the ExecStart path if command -v mailcatcher printed something other than /usr/local/bin/mailcatcher:

sudo useradd --system --shell /sbin/nologin mailcatcher
sudo tee /etc/systemd/system/mailcatcher.service > /dev/null <<'EOF'
[Unit]
Description=MailCatcher test mail server
After=network.target

[Service]
User=mailcatcher
Group=mailcatcher
ExecStart=/usr/local/bin/mailcatcher --foreground --no-quit --ip 127.0.0.1
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now mailcatcher
sudo systemctl status mailcatcher

Option 2: Install Mailpit

Mailpit is an actively developed mail catcher written in Go, with a web interface, a REST API for automated tests and optional relaying of selected messages to a real SMTP server. Its install script downloads the latest release to /usr/local/bin/mailpit. Read the script before you run it, as you should with anything piped into a root shell:

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

Create a service account and a directory for the message database:

sudo useradd --system --shell /sbin/nologin mailpit
sudo install -d -o mailpit -g mailpit -m 750 /var/lib/mailpit

Create the unit file. Mailpit listens on all interfaces unless told otherwise, so this unit binds both ports to localhost:

sudo tee /etc/systemd/system/mailpit.service > /dev/null <<'EOF'
[Unit]
Description=Mailpit server

[Service]
ExecStart=/usr/local/bin/mailpit -d /var/lib/mailpit/mailpit.db --listen 127.0.0.1:8025 --smtp 127.0.0.1:1025
Restart=always
RestartSec=10
SyslogIdentifier=mailpit
User=mailpit
Group=mailpit

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now mailpit
sudo systemctl status mailpit

Mailpit keeps the 500 most recent messages by default; change that with --max. To update Mailpit later, run the install script again and restart the service.

Send a test message and open the web interface

Send a message to port 1025 with curl, which works the same for both tools:

printf 'From: app@example.com\nTo: deploy@example.com\nSubject: Test message\n\nHello from the test server.\n' > /tmp/test-mail.txt
curl --url smtp://127.0.0.1:1025 --mail-from app@example.com --mail-rcpt deploy@example.com --upload-file /tmp/test-mail.txt

With the service bound to localhost, view the web interface through an SSH tunnel from your own computer. Use port 1080 for MailCatcher or 8025 for Mailpit:

ssh -L 1080:127.0.0.1:1080 deploy@203.0.113.1

Then open http://127.0.0.1:1080 in your browser. The test message should be listed.

Point your application at the catcher

Set your application's SMTP host to 127.0.0.1 and the port to 1025, with no encryption and no user name or password. For PHP's mail() function, which calls a sendmail binary rather than SMTP, Mailpit can stand in for sendmail; set this in php.ini:

sendmail_path = /usr/local/bin/mailpit sendmail

Allow access from other machines (optional)

If applications on other servers must deliver to the catcher, or colleagues need the web interface without a tunnel, change the listen address in the unit file to 0.0.0.0 and open the ports only for known addresses:

sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="198.51.100.20" port port="1025" protocol="tcp" accept'
sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="198.51.100.20" port port="1080" protocol="tcp" accept'
sudo firewall-cmd --reload

Replace 1080 with 8025 for Mailpit. Mailpit can additionally protect its web interface with a password file through --ui-auth-file.

Frequently asked questions

Is MailCatcher still maintained?

It still gets releases, but infrequently. The current release dropped support for Ruby 3.0 and older, which is why the default Ruby on the RHEL 9 family no longer works. If gem install mailcatcher fails while compiling an extension, check ruby --version first, then that the development packages listed above are installed.

What about MailHog?

MailHog was a popular alternative, but it has not received development or security updates for several years. Mailpit was inspired by it and is the usual replacement.

Can a mail catcher deliver some messages for real?

MailCatcher never delivers anything. Mailpit can release a captured message through a real SMTP server that you configure, optionally limited to an allowlist of recipients, which is useful when a tester needs one message in an actual inbox.

Can I run either tool in a container instead?

Yes. MailCatcher publishes the sj26/mailcatcher image, started with docker run -p 1080:1080 -p 1025:1025 sj26/mailcatcher, and Mailpit provides official images as well. A container avoids installing Ruby on the host at all.

Share story:

Continue reading other guides on How VPS.