Email Debugging with MailCatcher

You use email in your applications, right? Ok, that’s a rhetorical question. Of course you do. Despite email being over 30 years old, it’s still the most popular application on the planet, by far. Here are some stats from Pingdom, for 2012:

  • 2.2 billion – Number of email users worldwide
  • 144 billion – Total email traffic per day worldwide
  • 4.3 billion – Number of email clients worldwide in 2012

Staggering!

But why another article on email?

For one simple reason, one which we’ve likely all been caught by at one point or another. Because we need to test, as close to production as we can, but without emailing our clients accidentally, and them consequently becoming confused or frustrated, or embarrassed that their clients have received test emails.

I’m sure you know what I mean. You think you’ve set your application in some kind of debug mode. Given that, you start your test, which sends a load of emails from your application. All the while, you feel comfortable in the knowledge that no one but you is ever going to see them.

Your tests pass, you congratulate yourself, and move on. A short time later, you receive a rather, let’s just say terse, Skype call from your client. She’s rather annoyed as her customers have been ringing up, asking why they’ve been receiving odd emails from her company. She’s not happy and wants answers?

Been there? Don’t want to be there again? I’m guessing you don’t. Here’s the solution – MailCatcher. If you’re not familiar with it, 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.

Sound like a good solution? No matter if you’re tired, under pressure, new on the team, or just need to run tests – MailCatcher will ensure that no email ever gets sent outside of your network, or even outside of your development virtual machine.

In this post, I’m going to show you how to set it up and run through the interface when emails have been captured by it.

A Pre-Prepared Virtual Machine

To save you a lot of trouble of getting MailCatcher set up, I’ve created a custom Vagrant box which does it all for you. Make sure you have VirtualBox and Vagrant installed, then clone a copy of the article’s repository using the following command:

git clone git@github.com:sitepoint-examples/mailcatcher-article.git

Then, in the cloned project directory, run the following command:

vagrant up

This will launch the virtual machine provisioning process, displaying quite a lot of output as the provisioning process runs. The configured virtual machine is quite minimalist. It has MailCatcher, Sendmail and Nginx installed.

Nginx has a simple VHost setup, which maps the project directory to /var/www/ on the virtual machine. If you’d like to know exactly what happens during provisioning, checkout provision.sh.

Manually Installing MailCatcher

If you want to install MailCatcher yourself, and you have a virtual machine (or a Linux machine available), here are the steps to run:

sudo apt-get install -y vim curl python-software-properties lynx nginx
sudo apt-get install -y php5-fpm php5-memcache memcached php-apc
sudo apt-get install -y build-essential libsqlite3-dev ruby1.9.3
sudo gem install mailcatcher
sudo mailcatcher --http-ip 0.0.0.0

You may or may not have to run the third command. I did as I’m using a very minimalist Ubuntu Precise 64 Vagrant image, which needs the packages to build MailCatcher. Please be aware that if you’re on a different Linux distribution or version, the individual package names may be different.

Note: if you follow the standard MailCatcher startup process, it will only listen on IP 127.0.0.1, and port 1025. With this setup we couldn’t see it from the host machine. So I’ve added a public IP on the virtual machine, 192.168.56.111 and changed MailCatcher’s configuration so that it listens on all IPs.

The MailCatcher Web UI

Now you’ll be able to see the MailCatcher web UI at http://192.168.56.111:1080. It will look like the image below:

MailCatcher UI

It’s a pretty simple interface, listing the emails in the MailCatcher queue, when available, at the top. When there are emails in the list, the bottom pane does a good job of showing you information about them, which we’ll see later.

Sample Code

For this article, I’ve created a simple PHP script, index.php, available in the project repository, and accessible at http://192.168.56.111. It uses SwiftMailer to connect to MailCatcher and send an email on load. You can see in the code below a fairly standard HTML page.

<?php require_once('mail-loader.php'); ?>
<html>
<head>
    <title>Simple MailCatcher PHP Example</title>
</head>
<body>
    <h1>Simple MailCatcher PHP Example</h1>
    <p>This application sends a number of emails which will be caught by MailCatcher. To check them, view them in <a href="http://192.168.56.111:1080/" target="_blank">the local MailCatcher installation</a></p>
</body>
</html>

It includes mail-loader.php, which is available below.

<?php
require('vendor/autoload.php');
$email = 'matthew@example.com';
$subject = 'testing';
$message = 'test message';

$transport = Swift_SmtpTransport::newInstance(
    "localhost", 1025
);

$message = Swift_Message::newInstance();
$message->setTo(array(
    "matthew@maltblue.com" => "Matthew Setter",
));
$message->setSubject(
    "This email is sent using Swift Mailer"
);
$message->setBody("You're our best client ever.");
$message->setFrom("matthew@localhost", "Your bank");

$mailer = Swift_Mailer::newInstance($transport);
$mailer->send($message, $failedRecipients);
print_r($failedRecipients);

If you’re not familiar with SwiftMailer Aurelio’s article here on SitePoint provides an excellent introduction. Incidentally, it’s his code I’ve used for this example. Thanks Aurelio.

Basically, there’s only one line that’s important for us to note, which is the following:

$transport = Swift_SmtpTransport::newInstance(
    "localhost", 1025
);

This creates a connection to the MailCatcher server which we’ve just set up. That’s it, nothing fancy! I’ve now reloaded the page three times, which has sent three emails. You can see that they’re listed in MailCatcher in the image below.

MailCatcher UI Showing Mail Content

I’ve clicked on the first entry, which shows the received, from, to and subject details, as well as the body of the email. If we switch to the Source tab, as in the image below, we can see the raw email details:

MailCatcher UI Showing Raw Mail Content

Via the third tab, we can use Fractal to analyse the content of our email. I’ll skip that today as it’s beyond the scope of this article.

We’re All Set

With that done, we can now create emails as we otherwise would, setting recipients, subjects, attachments and so on, like I have above, and know that they will never actually go to the real addresses.

We can write tests to verify that the code works as it should. We can check the mail sending workflow, check message contents, recipients, headers and so forth. It’s as practical as it gets, without actually sending anything outside of our environment.

Now we can rest assured that our clients (and their clients) will never receive any emails that were never intended for them. What a relief.

Wrapping Up

Now, this is a rather trivial example, only using a simple SwiftMailer code snippet for the example. I’m sure that your codebases are much more complex and sophisticated than this example.

But I’m sure that in your applications, you’ll have debug and test configurations available, where you can set the host and port accordingly, differentiating it from live. By doing so, no other code will ever need to change, and you can reap the benefits of the peace of mind MailCatcher brings.

Do you already use MailCatcher? What’s your experience of integrating it? Were there any issues which caught you unaware? Share your thoughts in the comments.

Free book: Jump Start HTML5 Basics

Grab a free copy of one our latest ebooks! Packed with hints and tips on HTML5's most powerful new features.

  • Mark

    thanks for your article. sounds like a good way to test emails.

    • http://www.matthewsetter.com/ Matthew Setter

      I’ve found it to be quite the helping hand since using it. Nothing’s perfect, but it goes a long way towards it.

  • Taylor Ren

    Cool feature. Good to learn.

    • http://www.matthewsetter.com/ Matthew Setter

      Thanks @taylorren:disqus. Hope you find it helpful.

  • http://magnetikonline.com/ Peter Mescalchin

    Good article Matthew. I tackle this in a slightly different way, much less flair than using MailCatcher which looks rather nice on the UI front – it’s just a simple bash script that writes to a log file.

    https://gist.github.com/magnetikonline/6059512

    Set the script executable for the running PHP user, update PHP.ini then all mail() calls will be logged to file which can be tailed.

    • http://www.matthewsetter.com/ Matthew Setter

      Hey @petermescalchin:disqus looks interesting. I’m quite a fan of simple and effective solutions. Thanks for sharing.

  • Jose Domingos Grieco

    Matthew, I tried to clone the VM but the repository does not exists

    • http://www.matthewsetter.com/ Matthew Setter

      @josedomingosgrieco:disqus thanks for letting me know. I’ll get that sorted out.

    • http://www.bitfalls.com/ Bruno Skvorc

      Thanks, fixed the repo URL now

  • Roman

    Is there an alternative for Windows?

    • http://www.matthewsetter.com/ Matthew Setter

      I’m not really in a position to advise on Windows, as I’m not a user of it, except for only occasionally. Try out the commands at http://mailcatcher.me/#how. Alternatively, check out the response from @gazugafan above.

    • hot_rush

      you can use free online tool with same functionality http://debugmail.io/

  • http://www.matthewsetter.com/ Matthew Setter

    Hi Matt, thanks for sharing the information and code samples. I’ll be sure to check it out soon.

  • http://www.matthewsetter.com/ Matthew Setter

    @davertMik:disqus thanks for sharing. That’s quite a hearty article.

  • http://www.matthewsetter.com/ Matthew Setter

    Mourad, thanks for pointing that out. I appreciate that it doesn’t need to, but was only intended as a simple, demonstrative, example.

  • http://www.matthewsetter.com/ Matthew Setter

    Thanks for sharing. This helps fill in the gaps in my knowledge, as I’m a Mac/Linux user.

  • http://leopard.in.ua/ le0pard

    If you don’t want setup anything, you can use https://mailtrap.io. It also have spam analyze, blacklist and virus check, CSS check for email clients (like Fractal tab in Mailcatcher, but working, because Fractal service is dead). Also it have perfect REST and POP3 API for integrations.

    • http://www.matthewsetter.com/ Matthew Setter

      @le0pard:disqus thanks for sharing. I’d not heard of mailtrap till now, and it looks like a decent service.

  • temporaryuser381

    Well i’m on a windows platform and i use TestMAil Server. it doesn’t nned any setting up and we just need to install it. It will also save caught emails in files with .eml extension. Best solution for testing emails on localhost

    • http://www.matthewsetter.com/ Matthew Setter

      Nice one. I admit that my experience on Windows is a bit limited as I’m primarily a Mac & Linux user. But it’s always good to know about options for all platforms.