MailCatcher is a tiny local SMTP server with a web inbox. Your app sends email to it, nothing is delivered to real people, and you read every message in the browser. This guide covers install, a working config for common stacks, and what to do when MailCatcher is not the right fit.
What MailCatcher does
- Runs an SMTP server on port 1025.
- Runs a web UI on port 1080 where every caught message is listed.
- Shows the HTML, plain text and source of each message, and lets you download attachments.
- Keeps messages in memory only, so a restart clears the inbox.
Install
MailCatcher is a Ruby gem and needs Ruby 3.3 or newer:
gem install mailcatcher
mailcatcherOpen http://127.0.0.1:1080 for the inbox. The SMTP server listens on 127.0.0.1:1025.
Useful flags:
mailcatcher --ip 0.0.0.0 --smtp-port 2525 --http-port 8080
mailcatcher --foregroundThe MailCatcher project advises against adding it to your Gemfile, because its dependencies can clash with your app's. Install it as a standalone gem instead.
Config examples
Ruby on Rails
# config/environments/development.rb
config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = { address: "localhost", port: 1025 }
config.action_mailer.raise_delivery_errors = falseNode.js (Nodemailer)
import nodemailer from "nodemailer";
const transport = nodemailer.createTransport({
host: "localhost",
port: 1025,
secure: false,
});
await transport.sendMail({
from: "app@example.test",
to: "dev@example.test",
subject: "Hello from local dev",
html: "<p>It works.</p>",
});PHP
; php.ini
sendmail_path = /usr/bin/env catchmail -f app@example.testcatchmail ships with the gem and forwards PHP's mail() output to MailCatcher.
Any other stack
Set the SMTP host to localhost, the port to 1025, and turn off TLS and authentication. MailCatcher accepts any credentials.
Quick test without code
printf "Subject: test\r\nFrom: a@example.test\r\nTo: b@example.test\r\n\r\nHello\r\n" | curl smtp://127.0.0.1:1025 --mail-from a@example.test --mail-rcpt b@example.test -T -The message should appear in the inbox right away.
Common problems
- Nothing shows up: check that your app uses port 1025 and not the default 25 or 587.
- TLS errors: MailCatcher does not speak TLS. Disable STARTTLS and SSL in your mailer.
- Docker: inside a container, localhost is the container itself. Use the host's address, or run MailCatcher with
--ip 0.0.0.0and point to it. - Messages vanish: they live in memory. Restarting MailCatcher clears them.
When to use something else
MailCatcher is great when Ruby is already on your machine. If you do not want a Ruby toolchain, look at these:
- Mailpit: a single binary with search and an API.
- MailHog: a similar idea in Go. It is no longer actively maintained.
- A catcher built into your dev workspace: one less process to start and remember. See our post on MailHog alternatives.
Summary
Install the gem, run mailcatcher, point SMTP at localhost:1025 and read mail at http://127.0.0.1:1080. For most stacks that is a two-line config change.

