Installation Guide - MailCatcher NG

Basic Installation

MailCatcher NG requires Ruby 3.2 or higher. Ensure you have Ruby installed:

ruby -v

Then install via RubyGems:

gem install mailcatcher-ng

Start the server:

mailcatcher
# View mail at http://127.0.0.1:1080
# Send mail to smtp://127.0.0.1:1025

Development Mode

Run in foreground with custom ports:

MAILCATCHER_ENV=development bundle exec mailcatcher \
  --foreground \
  --smtp-port 1025 \
  --http-port 1080

Framework Integration

Rails

Add to config/environments/development.rb:

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address: '127.0.0.1',
  port: 1025
}
config.action_mailer.raise_delivery_errors = false

Django

Add to settings.py:

if DEBUG:
    EMAIL_HOST = '127.0.0.1'
    EMAIL_HOST_USER = ''
    EMAIL_HOST_PASSWORD = ''
    EMAIL_PORT = 1025
    EMAIL_USE_TLS = False

PHP / Laravel

Update .env:

MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

PHP Mail Function

Update php.ini sendmail path:

sendmail_path = /usr/bin/env catchmail -f from@example.com

Docker

Run MailCatcher with the official Alpine Linux image:

docker run -d -p 1080:1080 -p 1025:1025 stpaquet/alpinemailcatcher

Then access the web interface at http://127.0.0.1:1080 and send mail to smtp://127.0.0.1:1025

View the image on Docker Hub

Command Line Options

mailcatcher ng --help

Options:
  --ip IP                    Set IP address for both servers
  --smtp-ip IP              Set SMTP server IP
  --smtp-port PORT          Set SMTP port (default: 1025)
  --smtp-ssl                Enable SSL/TLS support for SMTP
  --smtp-ssl-cert PATH      Path to SSL certificate file
  --smtp-ssl-key PATH       Path to SSL private key file
  --smtp-ssl-verify-peer    Verify client SSL certificates
  --smtps-port PORT         Direct TLS port (default: 1465)
  --http-ip IP              Set HTTP server IP
  --http-port PORT          Set HTTP port (default: 1080)
  --messages-limit COUNT    Keep only N most recent messages
  --persistence             Store messages in a persistent SQLite database file
  --http-path PATH          Add prefix to all HTTP paths
  --no-quit                 Disable quit functionality
  -f, --foreground          Run in foreground
  -b, --browse              Open web browser on start
  -v, --verbose             Be more verbose
  -h, --help                Show this help
  --version                 Show version

Persistent Storage

By default, MailCatcher NG stores messages in memory and they are lost when the process terminates. Enable persistent storage to keep messages across restarts:

mailcatcher --persistence

Messages will be stored in a SQLite database file at ~/.mailcatcher/mailcatcher.db

Docker with Persistent Storage

When using Docker, you need to mount a volume to persist the database file. Note: The current Docker image does not yet include support for the --persistence flag. This feature will be added in a future release.

docker run -d \
  -p 1080:1080 \
  -p 1025:1025 \
  -v mailcatcher_data:/root/.mailcatcher \
  stpaquet/alpinemailcatcher

Or with a bind mount to a host directory:

docker run -d \
  -p 1080:1080 \
  -p 1025:1025 \
  -v /path/to/local/storage:/root/.mailcatcher \
  stpaquet/alpinemailcatcher

SSL/TLS Configuration

MailCatcher supports encrypted SMTP connections using SSL/TLS. You must provide your own certificate and private key files.

Generate Self-Signed Certificate (Testing)

openssl req -x509 -newkey rsa:4096 \
  -keyout mailcatcher-key.pem \
  -out mailcatcher-cert.pem \
  -days 365 -nodes \
  -subj "/CN=localhost"

Start with SSL/TLS

mailcatcher \
  --smtp-ssl \
  --smtp-ssl-cert mailcatcher-cert.pem \
  --smtp-ssl-key mailcatcher-key.pem

This enables:

STARTTLS on port 1025: Upgrade to TLS (required before sending mail)
Direct TLS on port 1465: Encrypted from connection start (SMTPS)

Framework Configuration with TLS

Rails with STARTTLS

config.action_mailer.smtp_settings = {
  address: '127.0.0.1',
  port: 1025,
  enable_starttls_auto: true
}

Rails with direct TLS (SMTPS)

config.action_mailer.smtp_settings = {
  address: '127.0.0.1',
  port: 1465,
  enable_starttls_auto: false,
  ssl: true
}

Django with TLS

if DEBUG:
    EMAIL_HOST = '127.0.0.1'
    EMAIL_PORT = 1465  # Direct TLS
    EMAIL_USE_TLS = True
    EMAIL_USE_SSL = True

PHP with TLS

MAIL_PORT=1465
MAIL_ENCRYPTION=ssl  # or 'tls' for STARTTLS on port 1025

Production Certificates

For production-like testing, use certificates from your CA or Let's Encrypt:

mailcatcher \
  --smtp-ssl \
  --smtp-ssl-cert /etc/ssl/certs/your-cert.pem \
  --smtp-ssl-key /etc/ssl/private/your-key.pem \
  --smtp-ssl-verify-peer

Security Notes

Certificate and key files must be readable by the user running MailCatcher
STARTTLS is REQUIRED when SSL is enabled (no plain SMTP allowed)
Self-signed certificates will trigger warnings in most mail clients
Client certificate verification is disabled by default

Troubleshooting

Port Already in Use

Use different ports:

mailcatcher --smtp-port 2025 --http-port 2080

Ruby Not Found

Ensure Ruby 3.2+ is installed:

brew install ruby  # macOS
apt install ruby   # Ubuntu/Debian

Build Tools Missing

Install build tools for gem compilation:

apt install build-essential  # Ubuntu/Debian
xcode-select --install      # macOS

RVM Users

MailCatcher may only be available in the Ruby version it was installed in:

rvm default@mailcatcher --create do gem install mailcatcher
ln -s "$(rvm default@mailcatcher do rvm wrapper show mailcatcher)" "$rvm_bin_path/"

Build from Source

git clone https://github.com/spaquet/mailcatcher.git
cd mailcatcher
bundle install
bundle exec rake package
gem install mailcatcher-ng-VERSION.gem

Installation & Setup