Test Emails Locally with MailCatcher

One of the more difficult things to test when you’re developing a website on your local setup is emails. Whether it’s order confirmation emails for an ecommerce site or an email thanking a new member for signing up, when you’re testing on your own computer before deploying out to a development or staging server, those emails usually don’t get sent.

Depending on your setup – MAMP, WAMP, XAMPP, and all the amps – there may be a way to configure things so emails go out. Sometimes, though, it just doesn’t work. Or maybe during testing you’re sending to or from a bogus email address to avoid sending anyone a real email. What then?

Enter MailCatcher.

What is MailCatcher?

To quote from the MailCatcher site, “MailCatcher runs a super simple SMTP server which catches any message sent to it to display in a web interface.” In simpler terms, MailCatcher will “listen” for emails and “sends” them to the web interface which looks kind of like a mail app. Ever since learning about it, MailCatcher has become an invaluable tool in our web development process. (Hat tip to our friend Matt Weinberg.)

Installing & Setting It Up

Installing MailCatcher is ridiculously easy:

  1. Open up your command line app (Terminal for Mac and whatever is best for Windows; sorry, we’re Mac users here at Block 81).
  2. Type gem install mailcatcher and hit Return / Enter.

That’s it. It’s installed on your machine. To actually get MailCatcher running, you have a couple of methods:

  1. Open up your browser and go to http://localhost:1080/
  2. Or, in the command line, type the following: mailcatcher --smtp-port 30000 -b

Using option two above, we’re telling MailCatcher to use SMTP port 30000 and to open the browser for us (`-b`). There are other commands you can use; just type mailcatcher --help to view them in the command line.

One thing I personally ran into when I first started using MailCatcher is that it flat out didn’t work. If I recall, I kept getting errors about using the wrong port or something to that effect. After some research though (and RTFM), I was able to find the solution.

I use MAMP Pro on my local setup, so I needed to make some adjustments to my php.ini file. You may need to as well, so here’s how to go about it:

Open up MAMP and head to File > Edit Template > PHP. In that menu, you’ll see options for php.ini files for the various PHP versions you have installed in MAMP. You’ll want to choose whichever is your default or most common one for your setup. For instance, on my setup PHP 5.5.18 is my default PHP version, so I would choose PHP 5.5.18 php.ini.

That file will then open up and you’ll get a warning about how dangerous it is to modify it. No worries, just click OK.

Next you’ll want to scroll down to where it says mail function. It’s easier to simply do a search for it like so:

Now you’ll need to make some edits per the MailCatcher docs (in our case, we use PHP so we’ll follow those steps).

  • Change smtp_port = 25 to smtp_port = 1025
  • Uncomment ;sendmail_from = me@example.com by removing the semicolon in the front. The value doesn’t really matter so you can leave it as-is.
  • Uncomment ;sendmail_path = and set the value to /usr/bin/env catchmail —smtp-port 30000 -f me@example.com. Keep in mind that I’ve set that value like that because of how I have RVM setup. Refer to MailCatcher’s docs for more info.

Using MailCatcher

So here comes the fun part – using MailCatcher. I like to do a quick test to make sure it’s working. This is going to depend on what you’re working on exactly. For us, we do a lot of content management system and ecommerce work, particularly in ExpressionEngine. So once you have MailCatcher running, open up your local version of ExpressionEngine and log into the control panel. From there head to the Communicate page under Tools and send a test message. Then head over to MailCatcher and you should see your email.

Once you know it’s working then testing emails for your particular site should be a cinch.

I’m by no means an expert in MailCatcher, but if you have questions, feel free to ask on Twitter.

A Little Freebie

Running MailCatcher is pretty fun and it’s nice to see that your stuff is actually working and sending emails. Often that means you have to design and code up an HTML email. A lot of folks hate those, but I like them as they give a company’s brand a nice feel. So here’s a freebie template you’re free to use in your projects:

Killing MailCatcher: Something’s using port 1025

Using Web UI

MailCatcher runs as a daemon by default. Go to the web interface to quit.

Using Cmd Line

In OSX, run the following in a shell:

sudo lsof -nP -iTCP:1025 -sTCP:LISTEN

The expected output of this command is a process, which is listening on port 1025:

ruby    43841 youruserid    9u  IPv4 0x6a1610da80bb9b4f      0t0  TCP (LISTEN)

In the output above, the 2nd value is the process ID. Then, to kill the offending process (substitute in the correct PID):

sudo kill 43841

Download it from GitHub