Jason on
8th December 2017

Today we’re going to look at installing the extremely useful utility that is MailCatcher. But first, what is MailCatcher? As its name suggests MailCatcher catches mail – any outgoing mail from a system (if routed properly) will not go out in to the web and is captured in a local mailbox for you to view and debug.

This can be useful for a variety of reasons, I’ll start this post with a short story about a situation that could’ve been avoided had I been using MailCatcher at the time: I was carrying out some enhancement work on a WooCommerce shop that was already in production. After getting my local copy set up I noticed it was one of those stores where the orders are left at processing and the store owner hadn’t come back in to hit the completed button. My OCD took over and I immediately bulk edited the orders to complete – this of course emailed all of the customers in the store way back to the beginning with their order complete emails! Lesson learned, but this got me thinking that there must be a better way to handle mail on local environments.

A couple of other benefits that weren’t immediately evident but I feel like I’d miss now are the speed of the delivery to the local mailbox MailCatcher provides: you fire the action that sends the email and it’s there immediately, no waiting for SMTP handshakes or IMAP syncs. It’s probably only a couple of seconds faster, but as a developer I really appreciate that time saving.

Also mail clients, be it Gmail, Outlook or any of the others usually modify incoming HTML emails. The reason for this, as anyone who has worked on a newsletter is likely to know, is because the HTML engines and parsers used are woefully outdated. As far as I have seen, MailCatcher reproduces the email code verbatim, which is very handy for debugging visual difference in mail clients.

The last benefit I can think of right now is that when you’re using a large amount of third party code, for example WordPress and a bunch of plugins, the platform may actually send emails you didn’t know about! Because MailCatcher is capturing all mail, no matter the destination, you can see what is going out and when. John Blackbourn recently put together this useful gist with all of the situations where WordPress core will send an email.

Installing MailCatcher

These were the steps I followed to get MailCatcher going

  1. MailCatcher itself is a ruby gem, it can be installed globally by opening a terminal and running gem install MailCatcher
  2. We can now tell our php to use the catchmail binary that was installed with MailCatcher by editing the sendmail path in php.ini:
    sendmail_path = /usr/bin/env catchmail -f somebody@example.com
    (I use example.com as it is reserved and can never be registered.)
  3. Once you’ve saved php.ini and restarted php you can run mailcatcher in the terminal then browse to http://localhost:1080/ in your web browser. Any mail sent by php will arrive in this private inbox!

A couple of gotchas: The mail is cleared upon closing the tab. You have to run mailcatcher every time you reboot.

After setting up MailCatcher for the first time it’s almost set and forget, which I love. There’s no extra steps every time you start working on a new site or set up a new environment. The only requirement would be that you restart the daemon when you restart your computer (who does that anyway?!) and it wouldn’t be very difficult to even automate this step.