Setup a testing mail server using PHP on macOS Sierra

Changelog

November 15, 2016
Update instructions to work on macOS Sierra. Fix bug with deleting older saved eml files.

What is this?

You may already know this feeling. You've spent a few hours developing a shell script to send out billing emails to customers and after pressing "enter" you suddenly realise that your script is sending out hundreds of dummy emails to your customers (you had copied some data from the live server "just to test things out a bit").

You quickly stop the script, but the damage is already done! You're now getting confused emails from your customers... time to start writing that apology email!....... OR... you could implement a testing mail server so this situation NEVER HAPPENS AGAIN!

How does it work?

1. When an email is sent using PHP's mail() function, the email is piped through to the smtp_catcher.php script.
2. The smtp_catcher.php script saves the email into a local folder as a .eml file.
3. The email is opened through Apple Mail and displayed on the screen (woo!).

Why should I use this?

1. You don't need to change any of your application code. All emails will be routed through the smtp_catcher.php script and not sent through the interweb.
2. You can preview exactly how your email will look when it's received by your users, including the original recipients "To" address, any attachments and email headers.
3. You will never mistakenly send an email out when testing your email sending code.
4. Emails are saved and opened instantly, so no waiting for your email to travel through multiple mail servers to arrive in your inbox.

How do I install it?

Open a terminal window and copy and paste the following...

cd ~/ && mkdir smtp_out && cd smtp_out
curl -o smtp_catcher.php https://raw.githubusercontent.com/ifunk/smtp-catcher/master/smtp_catcher.php
chmod +x smtp_catcher.php

Now you've got the output folder created and the smtp_catcher.php script installed, you just need to update your php.ini and set some permissions.

NB. If your php binary is not in /usr/bin/php then you will need to edit the first line of smtp_catcher.php.

Configure PHP to pipe emails to the smtp_catcher.php script

Open up your php.ini file and find the following line. Please note, if you have a separate php.ini file for your CLI binary, you'll need to edit that one as well.

;sendmail_path =

Change it to the following (replacing <your_username> with your macOS username).

sendmail_path = sudo -u <your_username> /Users/<your_username>/smtp_out/smtp_catcher.php

Save your changes and restart your webserver.

Give permission to PHP to open Apple Mail

PHP runs as the _www user by default, which will mean smtp_catcher.php won't be able to open your GUI mail program, so we have to give sudo access to the _www group. If you are not using the Apache/PHP that comes pre-installed in Mac OS X, then you may need to change _www to suit your needs. Mac OS X versions prior to macOS Sierra should use www instead of _www.

sudo visudo

Add the following line to the sudoers file and save (replacing <your_username> with... yep, your username).

%_www    ALL=(ALL)   NOPASSWD: /Users/<your_username>/smtp_out/smtp_catcher.php

This will now give permission to PHP to execute the smtp_catcher.php script with sudo permissions, without having to enter a password!

Test it to make sure everything works

The final step is to create and execute a test script, which can be as simple as this.

<?php
mail('john.doe@example.com', 'The Magical Subject Line', 'The Magical Message Body');

What if I'm using PHP on Windows?

Easy! Install the Test Mail Server Tool and uncomment the following lines from your php.ini, and restart your webserver.

SMTP = localhost
smtp_port = 25