Stand with Ukraine 🇺🇦 Donate to support

Introduction to Mailcatcher

On September 12, 2019
6min read
Piotr Malek Technical Content Writer @ Mailtrap

Setting up email workflows for your app might be difficult. The framework you use might not necessarily be built with emails in mind (think, ReactJS for example). Even when you figure that out, how do you ensure the right emails are sent to the right recipients? How do you make them look beautiful on all screen sizes? How do you avoid random spam waves triggered accidentally when using production data in a pre-production environment? Some of these can be, to some extent, answered with a tool called MailCatcher.

What’s MailCatcher?

MailCatcher is a free tool that can intercept emails sent from any web or mobile app. It works as a fake SMTP server where you redirect your messages to instead of sending them to a real SMTP server. Emails sent this way arrive only to a local server and can be viewed in a web interface. Or maybe they don’t arrive at all. If the latter is the case, you probably have some work to do here.

Each message that arrives to Mailcatcher can be opened and analyzed. You can look into its body, headers, attachments, and HTML code of the entire message. Mailcatcher works with any framework that supports SMTP and localhost, so the list of available options is very long. The tool can also be initiated over API.

How to set up Mailcatcher?

Mailcatcher runs on Ruby so you’ll need to have a development environment set up. Here’s how you can do this for the following versions:

Many other versions of Ubuntu and Mac OS are also covered under the links above. For each, solely the “Installing Ruby” part will be sufficient to set up the environment for installing Mailcatcher.

When you’re done, install Mailcatcher with the following:

gem install mailcatcher

Or use Bundler to do this. Install it first:

$ gem install bundler

Specify the dependencies in a Gemfile:

source ''
gem 'mailcatcher’

Whichever approach you choose, Mailcatcher should be installed so you might as well just start it:

mailcatcher --ip

or just 


NOTE: Skipping the zeros is fine for most cases. But if you wish to use a docker to install or simply want to share your Mailcatcher view with other machines, add “” in the end.

You should see the following:

root@install:~# mailcatcher --ip
Starting MailCatcher
==> smtp://
*** MailCatcher runs as a daemon by default. Go to the web interface to quit.

Speaking of a docker – instead of installing a gem as in the example above, you can use the dedicated docker image.

First of all, add it to your docker-compose.yml file.

  image: schickling/mailcatcher
     - 1080:1080

Make sure this container is linked to your app container and use the following SMTP settings:

  server: mail
  port: 1025

Now, you can set the workflows you were planning to test to be sent through smtp://[]:1025 and access them at http://[]:1080/

For the list of framework-specific instructions for installing Mailcatcher, check the list on their homepage.

When in doubt, check also the list of available commands by typing:

mailcatcher --help

which will return:

mailcatcher --help
Usage: mailcatcher [options]
       --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
       --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

A particularly useful option is to launch Mailcatcher in a foreground so others can connect to your local SMTP. Do this by:

mailcatcher --foreground --ip=

Why use Mailcatcher?

Despite its basic functionalities, Mailcatcher can effectively prevent you from spamming real users of your app. Since all the workflows you’re testing will be redirected to a local address, no message will ever be delivered to an actual SMTP server and then pushed to users’ inboxes (assuming you configured everything correctly).

With this tool, you can also easily see what really works and what doesn’t. In other words, you can see if a message that was supposed to be triggered is really sent. You can also be notified when a flood of emails is released after a simple action by a user and fix it before pushing it to production.

Mailcatcher can also help you perform a basic inspection of the content and headers of your emails. You can access the HTML version of an email, and check if the headers, including Return-Path address, are set correctly. You can also try out the links, preview the attachments, and diagnose what needs to be improved before an email is sent.

Finally, Mailcatcher is free to use, which might be appealing to those of you on a very low budget. The developer of this tool can be supported with donations but other than that, all of the features listed above are free of charge.

This is all great, but are there any disadvantages of using this tool?

Start Testing

Mailcatcher cons

Yes, Mailcatcher also has various limitations and drawbacks.

Not developed further for years

The last release (0.6.4) was made available back in February 2016. Although there have been some minor updates to the repository since then, there’s little sign of new upcoming features. If you’re willing to pay for adding new functionalities, you’re encouraged to get in touch with the author.

Very basic web client

What you see at is a basic tool for verifying if emails are received or not and if headers were set up as expected. By all means, it can be enough for some tests, but if you need more, you’ll need to look somewhere else. Mailcatcher will preview each message and might give some (visual) hints when something doesn’t render as expected. It’s important to keep in mind, though, that a thing or two might have been changed in the world of browsers since the last update to Mailcatcher. For example, at the time of the last release, Google Chrome was just celebrating the launch of version 48.0.2564, Adobe Flash Player was in full swing, and HTML5 was just optional. At the time of writing, Chrome is in its 76th version, with new versions lurking right behind the horizon.

Takes time and effort to set up

Since Mailcatcher is not a web service, you need to take care of hosting it somewhere. For that, you’ll need to set up a server and then install Mailcatcher using the instructions we mentioned above. Mailcatcher is built with Ruby and usually deployed with Ubuntu. If this is not your field of expertise, it might take a bit of an extra effort to get things going. 

Both local and cloud-based testing environments have certain benefits, with the latter one being usually a preferred option for developers and QAs. Either way, we’ve covered the differences in another article.

No use for teams

Mailcatcher’s SMTP server works only on localhost, which might be perfectly fine if you’re the only person tasked with testing email workflows. If you, however, want to have some help, share your progress with a remote manager, or need to keep a client in the loop, Mailcatcher won’t be any good. As such, it’s good only for small, stationary teams and individuals.

Easy to get lost in

If you try to test just a few emails, you’re fine with a basic inbox. If you, however, have a complex project to work on which involves numerous workflows, different user permissions and teams are involved, your inbox will quickly be flooded and almost impossible to navigate. This might cause delays and make it difficult to spot something important as you progress.

Mailcatcher alternatives

If any of the listed cons is a deal-breaker for you, you’ll be happy to know that there are some Mailcatcher alternatives actively being developed. One of these tools is Mailtrap.

By its very nature, Mailtrap is also a fake SMTP server that captures your outgoing emails for testing purposes. Unlike Mailcatcher, Mailtrap is hosted in the cloud and, as such, is technology-agnostic. It doesn’t require any installation except for a brief SMTP configuration in the application. Having your testing environment accessible online allows anyone on your team or outside to access your inboxes (with your permission, of course!) and collaborate freely.

Learn how exactly Mailtrap can help you streamline email testing processes from our case study with The Software House.

Mailtrap comes with a sophisticated web dashboard, split into multiple inboxes to easily handle various projects at the same time. In the editor, you can preview each email and get detailed hints on what to improve in order to fix HTML and avoid visual failures. The editor also gives you hints on how to improve your deliverability to avoid spam filters.

Finally, Mailtrap comes with tons of additional features such as the ability to forward emails to coworkers, a dedicated email address to send test emails to, or an option to Bcc Mailtrap inbox to keep track of transactional emails being sent on the production environment. A support team and a large community of developers already using Mailtrap are also at your disposal.

Try Mailtrap for Free

Feel free to give it a try with a Free Forever plan. You can upgrade later if you need more features.

Article by Piotr Malek Technical Content Writer @ Mailtrap