Debugging Email with MailCatcher

Original author: Matthew Setter
  • Transfer
  • Tutorial
imageYou use email in your application, right? This is, in general, a rhetorical question, of course you use. She is over 30 years old, and this is still the most popular means of communication on the planet. Here are some statistics from Pingdom :
  • 2.2 billion - Number of email users worldwide
  • 144 billion - Daily emails sent worldwide
  • 4.3 billion - Number of email clients worldwide


Why is this article needed?

For one simple reason that we all face one way or another. It is necessary to test the functionality as close as possible to the real application, and any error can lead to the fact that our customers will receive test emails, and this will be sad.

I'm sure you know what I'm talking about. Thinking that you put the application in debug mode, you run a test that sends letters from your application. You think that no one except you will see these letters.

Tests pass, you praise yourself and continue to work. But after some time you receive a call from your customer. He complains that his customers got weird. He is upset and wants to get an answer.

It was so? Do not want to be repeated? There is a solution - MailCatcher . If you have not heard of him, then briefly:
... A super-simple SMTP server that intercepts any sent message and displays it in the web interface. Run mailcatcher, in your application settings, specify the smtp:// SMTP server instead, and then view the mail that was sent to127.0.0.1:1080

Sounds good, right? Regardless of whether you are tired, overworked, whether there is a newcomer to the team or something else, MailCatcher ensures that the email remains within your network, or even your virtual machine.

Now I want to show you how to configure, run and use MailCatcher.

Prepared Virtual Machine

To save you a little time, I created a Vagrant box with MailCatcher already configured. Make sure you have Vagrant and VirtualBox installed and clone your repository using the following command:
git clone

Then, going to the resulting directory, execute the command:
vagrant up

The process of initializing the virtual machine will start. Its settings are quite minimalistic, the kit includes MailCatcher, Sendmail and Nginx.
Note per .: if you use puphpet ( what is it ) to build virtual machines, then I note that the installation of MailCatcher is available in it as an option, well, a bunch of other goodies, I recommend.

Manually Installing MailCatcher

If you want to install MailCatcher yourself, here is the sequence of commands:
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

You may not need the 3rd command, but I use a fairly minimalistic image of Ubuntu Precise 64, and there were no necessary packages. If you use a different distribution, the packages and their versions may differ from the above.

Note. With a standard start, MailCatcher will only listen on ip and port 1025, in which case we would not see it from the outside. I changed the configuration so that it listened to all ip addresses and added public ip

MailCatcher Web Interface

Now, by clicking on can observe the web interface, it will look like this:
MailCatcher Web Interface
The interface is rather concise, in the upper part there is a list of emails received by MailCatcher. When there are letters in the list, then information about them will be displayed at the bottom, which we will see a little later.

Usage example

For this article, I created a simple php script, index.php, it is present in the repository, it is available at our address To send letters, the SwiftMailer library is used. Take a look at the code below:
Simple MailCatcher PHP Example

Simple MailCatcher PHP Example

This application sends a number of emails which will be caught by MailCatcher. To check them, view them in the local MailCatcher installation

He, in turn, connects mail-loader.php:
    "" => "Matthew Setter",
    "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);

If you are new to SwiftMailer, Aurelio's article on SitePoint will be a good start in exploring it. By the way, this is his code I used for this example. Thanks, Aurelio.

From the above script, for us, in principle, only one line of code is important:
$transport = Swift_SmtpTransport::newInstance(
    "localhost", 1025

This creates a connection to the MailCatcher smtp server, nothing complicated. Let's reload the page 3 times to send 3 letters. Here they are, in the image below:
Having selected the first record, we see information about the letter as well as its body. If we go to the tab Source, as in the image below, we will see the message headers: the
3rd tab will allow us to use Fractal to analyze the contents of the letter. I will skip it, because this is a bit beyond the scope of today's article.

Everything is ready for work

Now, having installed MailCatcher, we can send emails by setting recipients, subject, adding attachments, etc. We can write tests that check the entire process of the application, knowing that real users will not receive letters that are not intended for them. This can not but rejoice.


My example is pretty trivial, and I'm sure your code base is more complex and sophisticated, but regardless of this, you can take advantage of working with MailCatcher and be calm without any changes in your code.

Maybe you are already using MailCatcher? What can you say about the results of its integration, were there any questions that took you by surprise. I would be glad if you share your thoughts.

This and other translations from Sitepoint, as well as other articles on web development .

Also popular now: