/blog/mailcatcher-setup-example-config

MailCatcher setup, example and config: catch dev emails locally (and a simpler alternative)

20 November 2026 · 3 min read

An email envelope caught inside a glass jar on a desk next to a laptop (AI-generated illustration)

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
mailcatcher

Open 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 --foreground

The 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 = false

Node.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.test

catchmail 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.0 and 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.

FAQ

What ports does MailCatcher use?
By default MailCatcher accepts SMTP on 127.0.0.1:1025 and shows the web inbox at http://127.0.0.1:1080. You can change both with --smtp-port and --http-port.
Should I add MailCatcher to my Gemfile?
No, the MailCatcher project asks you not to, because its dependencies can conflict with your app's. Install it as a standalone gem with gem install mailcatcher.
Why are my MailCatcher messages gone after a restart?
MailCatcher keeps messages in memory only, so stopping or restarting it clears the inbox. Use a catcher with persistent storage, such as Mailpit, if you need to keep them.