Debugging email sending can be notoriously difficult. There are too many moving parts: the extension you are using, Joomla!'s mail setup in Global Configuration, your web server, your mail server, the other party's mail server and their mail client. Between them it's nigh impossible to know where a problem occurs. It would be of immense help being able to isolate just the code running on your web server when debugging email. This is done with MailCatcher.

MailCatcher is a brilliant piece of software which runs a special SMTP server on your local machine on port 1025. Instead of forwarding mail to the Internet it keeps it locally. You can then view the sent email by visiting http://127.0.0.1:1080 on your browser. This is very helpful in debugging email sending without risking a stray email ending up in one of your site's users' inbox by accident.

This articles deals on setting it up under Mac OS X for use with any local server environment. I'm using it with MAMP Pro and Zend Server. It can also be used with Mac OS X's own Apache / PHP installation, a custom-built local server setup, XAMPP and pretty much anything in between. If you improvise on the instructions a bit you can also use it on Windows and Linux. Or you could use my Vagrant box for a Linux virtual server with MailCatcher pre-installed and ready for action!

Installing MailCatcher

MailCatcher is written in Ruby. Mac OS X does come with a system-wide Ruby version pre-installed so it all boils down to an one-liner command.

Open a Terminal window and enter the command:

sudo gem install mailcatcher

It will prompt you to enter your user password. Text will flow on the screen and after a few minutes –depending on your Internet connection speed– the command will return. MailCatcher is now installed but not running yet.

Starting MailCatcher automatically

Start Automator: open the Launchpad, type Automator, click on the icon of a robot holding a length of pipe.

Select New, then choose Application.

Click Show library in the toolbar (if hidden).

Add Run shell script from Actions > Utilities.

Change the script to read /usr/bin/mailcatcher.

Click Run to test it. After a couple of seconds it should tell you that the script execution is complete.

Open your browser and go to http://127.0.0.1:1080

If everything worked you should see MailCatcher's page. If not, go back and retry following these instructions.

Go back to Automator and save your script (⌘-S) locally. Do NOT save to iCloud! Ideally you should use your home directory. Note down the directory you saved it in.

Go to System Preferences, Accounts, Login items and add your newly created Automator script. Also tick the Hide check box next to it to prevent the Automator window showing up when you log in.

Set up Joomla!

Remember that you installed MailCatcher on your local machine. Therefore you can only use it with sites running locally, on your machine. It will obviously NOT work with your live site!

Log in to your local Joomla! site's administrator back-end.

Go to System, Global Configuration and click on the Server tab.

Under Mail Settings set Send Mail to Yes and Mailer to SMTP.

Set SMTP Security to None and set SMTP Port to 1025.

Leave the SMTP Username and SMTP Password fields blank.

Set the SMTP Host field to 127.0.0.1

Click on Save & Close.

Testing MailCatcher

Log in to your local Joomla! site's administrator back-end.

Go to Users, Mass Mail Users.

Select a user group, enter a Subject and a Message, then click on Send email.

Note: this only works if you have at least a user besides yourself on the selected group. If you are the sole user it won't work!

Visit http://127.0.0.1:1080 with your browser. You should now see the email you just sent.

Bonus track: using MailCatcher with non-Joomla! scripts

If you're also using WordPress or any other script which doesn't go through Joomla!'s email system you're most likely using PHP's built-in mailer. This may also hold true for some Joomla! extensions which do not go through the JMail API. Fortunately, there is a way to use MailCatcher with it. It's just a bit more involved. You will need to edit your php.ini file.

The easiest way to find where your php.ini file lives is creating a new file called phpinfo.php with the following contents:

<?php phpinfo();

and visit it with your browser. Search for Loaded Configuration File, it's located towards the top of the page. Next to it there is something like /usr/local/zend/etc/php.ini. That's the file you need to edit.

Following MailCatcher's documentation you need to change the sendmail_path line to

sendmail_path = /usr/bin/env /usr/bin/catchmail -f This email address is being protected from spambots. You need JavaScript enabled to view it.

changing This email address is being protected from spambots. You need JavaScript enabled to view it. to the From email address you want to use with your scripts.

Words of warning

As noted above, some extensions might not go through Joomla!'s JMail API. You should set up php.ini per the instructions above to avoid accidental on-line delivery of mail during testing.

If you are using a plugin which overrides the mail configuration you will need to disable it. For example, if you're using the CMandrill Joomla! extension to deliver your mail with the Mandrill service you need to disable it, otherwise all your mail will be delivered via Mandrill!

As redundant as it may sound, if you are using a script with its own mail setup you must remember to set it up to use MailCatcher's SMTP server.

Finally, be a good sport and donate something to MailCatcher's developer like I did. He's saving you lots of time and effort.