[opensourcedex]

mailcatcher is a free, open source frameworks & platforms project written in Ruby and released under MIT. It has 6,779 GitHub stars, 605 forks and 43 open issues, and was last pushed 5 days ago. On this registry it ranks #35 of 58 tracked projects in Frameworks & Platforms, with 5 head-to-head comparisons available.

What is mailcatcher?

MailCatcher is a Ruby SMTP server that catches every message sent to it and serves those messages through a local web interface, and it is made for developers who need to inspect the email their application sends without delivering it to real recipients.

What it is

MailCatcher runs a simple SMTP server that accepts any message delivered to it and stores that message for display, rather than forwarding it onward. It lives in the Ruby ecosystem, ships as a RubyGem, and its topics place it alongside Rails and general Ruby web development tooling. The project also reaches into PHP projects, where the bundled catchmail command acts as a sendmail analogue.

The concrete problem it solves is accidental delivery during development. Instead of pointing an application at a real mail server, a developer points it at smtp://127.0.0.1:1025 and reads the captured mail at http://127.0.0.1:1080. It replaces the default SMTP server in a development environment, and for PHP it replaces the system sendmail binary through the sendmail_path setting.

Key capabilities

  • Runs an SMTP server and catches all mail, storing it for display in the web interface.
  • Shows the HTML, plain text, and raw source versions of each message, as applicable.
  • Rewrites HTML so embedded and inline images display and links open in a new window.
  • Lists attachments and allows separate downloading of individual message parts.
  • Downloads the original email so it can be opened in a native mail client.
  • Updates instantly over WebSockets where the browser supports them, and otherwise refreshes every thirty seconds.
  • Provides catchmail, a sendmail-analogue command, plus command line options including --smtp-ip, --smtp-port, --http-ip, --http-port, --messages-limit COUNT, and --http-path PATH.

Who uses it and how

  • Rails developers add config.action_mailer.delivery_method = :smtp with :address => '127.0.0.1' and :port => 1025 to environments/development.rb, setting config.action_mailer.raise_delivery_errors = false.
  • PHP projects and platforms such as Drupal set sendmail_path = /usr/bin/env catchmail -f [email protected] in php.ini, or set the same value in Apache with php_admin_value.
  • RVM users install it into a dedicated gemset via a wrapper script so the command stays available across rubies and gem conflicts are avoided.
  • Teams that cannot add it to a Gemfile instead note in their README that MailCatcher is used, and instruct contributors to run gem install mailcatcher followed by mailcatcher.
  • Developers keep the process in the background as a daemon or run it in the foreground with -f or --foreground, and can open a browser automatically with -b or --browse.

Getting started

Install with gem install mailcatcher, then run mailcatcher; the README states that Ruby 3.3 or newer is required, and upgrading works the same way as installation.

How it compares

The supplied facts name no alternative products, so within this registry MailCatcher stands alone as a self-hosted development mail catcher. Its licence is MIT, and no paid tier, hosted option, or cost model is described anywhere in the facts provided.

When to use it — and when not to

A self-hoster must operate the Ruby runtime described in the README, including build tools for gem dependencies: apt install build-essential on Debian or Ubuntu, or xcode-select --install on macOS, with a documented workaround for installing thin version 1.5.1 when its build fails. It should not be placed in an application Gemfile, because the README states it will conflict with the application's gems at some point. The supplied facts also do not describe authentication, TLS, message persistence beyond the process lifetime, or any production mail relay, and the README excerpt ends mid-sentence in the RVM section, so anyone needing production delivery or durable storage should look elsewhere.

project readme (upstream, from github) — read inline

MailCatcher

Catches mail and serves it through a dream.

MailCatcher runs a super simple SMTP server which catches any message sent to it to display in a web interface. Run mailcatcher, set your favourite app to deliver to smtp://127.0.0.1:1025 instead of your default SMTP server, then check out http://127.0.0.1:1080 to see the mail that's arrived so far.

MailCatcher screenshot

Features

  • Catches all mail and stores it for display.
  • Shows HTML, Plain Text and Source version of messages, as applicable.
  • Rewrites HTML enabling display of embedded, inline images/etc and opens links in a new window.
  • Lists attachments and allows separate downloading of parts.
  • Download original email to view in your native mail client(s).
  • Command line options to override the default SMTP/HTTP IP and port settings.
  • Mail appears instantly if your browser supports WebSockets, otherwise updates every thirty seconds.
  • Runs as a daemon in the background, optionally in foreground.
  • Sendmail-analogue command, catchmail, makes using mailcatcher from PHP a lot easier.
  • Keyboard navigation between messages

How

  1. gem install mailcatcher
  2. mailcatcher
  3. Go to http://127.0.0.1:1080/
  4. Send mail through smtp://127.0.0.1:1025

Command Line Options

Use mailcatcher --help to see the command line options.

Usage: mailcatcher [options]

MailCatcher v0.8.0

        --ip IP                      Set the ip address of both servers
        --smtp-ip IP                 Set the ip address of the smtp server
        --smtp-port PORT             Set the port of the smtp server
        --http-ip IP                 Set the ip address of the http server
        --http-port PORT             Set the port address of the http server
        --messages-limit COUNT       Only keep up to COUNT most recent messages
        --http-path PATH             Add a prefix to all HTTP paths
        --no-quit                    Don't allow quitting the process
    -f, --foreground                 Run in the foreground
    -b, --browse                     Open web browser
    -v, --verbose                    Be more verbose
    -h, --help                       Display this help information
        --version                    Display the current version

Upgrading

Upgrading works the same as installation:

gem install mailcatcher

Ruby

MailCatcher requires Ruby 3.3 or newer.

If you have trouble with the setup commands, make sure you have Ruby installed:

ruby -v
gem environment

You might need to install build tools for some of the gem dependencies. On Debian or Ubuntu, apt install build-essential. On macOS, xcode-select --install.

If you encounter issues installing thin, try:

gem install thin -v 1.5.1 -- --with-cflags="-Wno-error=implicit-function-declaration"

Bundler

Please don't put mailcatcher into your Gemfile. It will conflict with your application's gems at some point.

Instead, pop a note in your README stating you use mailcatcher, and to run gem install mailcatcher then mailcatcher to get started.

RVM

Under RVM your mailcatcher command may only be available under the ruby you install mailcatcher into. To prevent this, and to prevent gem conflicts, install mailcatcher into a dedicated gemset with a wrapper script:

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

Rails

To set up your rails app, I recommend adding this to your 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

PHP

For projects using PHP, or PHP frameworks and application platforms like Drupal, you can set PHP's mail configuration in your php.ini to send via MailCatcher with:

sendmail_path = /usr/bin/env catchmail -f [email protected]

You can do this in your Apache configuration like so:

php_admin_value sendmail_path "/usr/bin/env catchmail -f [email protected]"

If you've installed via RVM this probably won't work unless you've manually added your RVM bin paths to your system environment's PATH. In that case, run which catchmail and put that path into the sendmail_path directive above instead of /usr/bin/env catchmail.

If starting mailcatcher on alternative SMTP IP and/or port with parameters like --smtp-ip 192.168.0.1 --smtp-port 10025, add the same parameters to your catchmail command:

sendmail_path = /usr/bin/env catchmail --smtp-ip 192.160.0.1 --smtp-port 10025 -f [email protected]

Django

For use in Django, add the following configuration to your projects' settings.py

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

Docker

There is a Docker image available on Docker Hub:

$ docker run -p 1080:1080 -p 1025:1025 sj26/mailcatcher
Unable to find image 'sj26/mailcatcher:latest' locally
latest: Pulling from sj26/mailcatcher
8c6d1654570f: Already exists
f5649d186f41: Already exists
b850834ea1df: Already exists
d6ac1a07fd46: Pull complete
b609298bc3c9: Pull complete
ab05825ece51: Pull complete
Digest: sha256:b17c45de08a0a82b012d90d4bd048620952c475f5655c61eef373318de6c0855
Status: Downloaded newer image for sj26/mailcatcher:latest
Starting MailCatcher v0.9.0
==> smtp://0.0.0.0:1025
==> http://0.0.0.0:1080

How those ports appear and can be accessed may vary based on your Docker configuration. For example, your may need to use http://127.0.0.1:1080 etc instead of the listed address. But MailCatcher will run and listen to those ports on all IPs it can from within the Docker container.

API

A fairly RESTful URL schema means you can download a list of messages in JSON from /messages, each message's metadata with /messages/:id.json, and then the pertinent parts with /messages/:id.html and /messages/:id.plain for the default HTML and plain text version, /messages/:id/parts/:cid for individual attachments by CID, or the whole message with /messages/:id.source.

Caveats

  • Mail processing is fairly basic but easily modified. If something doesn't work for you, fork and fix it or file an issue and let me know. Include the whole message you're having problems with.
  • Encodings are difficult. MailCatcher does not completely support utf-8 straight over the wire, you must use a mail library which encodes things properly based on SMTP server capabilities.

Thanks

MailCatcher is just a mishmash of other people's hard work. Thank you so much to the people who have built the wonderful guts on which this project relies.

Donations

I work on MailCatcher mostly in my own spare time. If you've found Mailcatcher useful and would like to help feed me and fund continued development and new features, please donate via PayPal. If you'd like a specific feature added to MailCatcher and are willing to pay for it, please email me.

License

Copyright © 2010-2019 Samuel Cochran ([email protected]). Released under the MIT License, see LICENSE for details.

Frequently asked questions

Is mailcatcher free to use?

mailcatcher is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does mailcatcher do?

Catches mail and serves it through a dream.

What is mailcatcher written in?

mailcatcher is primarily written in Ruby. Its source is publicly available at https://github.com/sj26/mailcatcher, and it has 6,779 GitHub stars.