Using MailHog for local email testing

The problem

Testing contact forms or other outgoing email from your website/app locally can be a real pain. You have to set up your local webserver to enable mail and waste a lot of time waiting for mail to arrive in your inbox if it arrives at all. Additionally, you might even hurt your email address if you test with your private email as sender.

So, what are the alternatives?

One option is certainly the use of services like MailChimp and many others, which are not only useful for sending newsletters, but can also be used to send transactional emails. Many of these services also have a free tier for a limited amount of mails, and thus offer themselves for testing during development. However, for all these services you need an account, and that's probably not what you want.

What is MailHog?

MailHog is an Open Source email testing tool with a fake SMTP server underneath. It allows you to configure your application to send mail to MailHog instead of to your default SMTP server. MailHog catches all mail sent to it and stores them for display in a web-based user interface for you to view. MailHog runs on Windows, Linux, and MacOS. MailHog is also available as a Docker image, so if you are using Docker, you don't have to install MailHog on your system.

MailHog has some more interesting features that you can find in the feature list, including an API to list, retrieve and delete message or an option to release message to real SMTP servers.

Installation

You can either download the latest release for your platform from GitHub, or install with Homebrew on Mac, or on Linux install Go and then download MailHog from GitHub. See the MailHog documentation for details.

By default, MailHog runs with the following default settings:

SMTP server starts on port 1025
HTTP server starts on port 8025
Use of in-memory message storage

If your system already uses ports 1025/8025 for other services, you can configure MailHog to use other settings.

Configure Kirby to use MailHog

Once MailHog is installed and running on your system, you can start using it with Kirby. The easiest way to do so, it to set up email transportation in your (local) config file:

/site/config/config.php

return [
  'email' => [
    'transport' => [
      'type' => 'smtp',
      'host' => 'localhost',
      'port' => 1025,
      'security' => false
    ]
  ],
];

With Kirby, you can use multiple config files for different environments, so you can set up email transportation with MailHog for local development and with some other configuration for staging or production. See our multi-environment configuration docs.

A test email

Now we are ready for testing our first email.

For this test, you can either set up the form from our basic contact form Cookbook recipe or
you can be lazy and just put the following code into any template or controller, for example in a Starterkit that's already running on your system:

<?php

$kirby->email([
    'template' => 'email',
    'from'     => 'yourcontactform@yourcompany.com',
    'to'       => 'you@yourcompany.com',
    'subject'  => 'Let us test if MailHog works',
    'data'     => [
        'text'   => 'Here is some dummy text',
    ]
]);

But before we trigger sending of the email, we need an email template - so create /site/templates/emails/email.php with the following content:

/site/templates/emails/email.php

We are testing MailHog:

<?php echo $text ?>

Before you hit the send button of the form or open the page with the email code in the browser, let's verify that everything is in place:

MaiHog is up and running
Email transportation in your config is set to using SMPT port 1025 (or the port you have configured)
You can access the MailHog Web UI at localhost port 8025 (or the port you have configured)

Now go open the page with the email code in a browser, and if all went well, you should now see the newly sent mail in MailHog's Web UI:

If you put the email code into an arbitrary template instead of setting up a form, remember to remove it again after you have finished testing. Otherwise you will see an error if MailHog is not running and you want to visit that page again some time later, when you have long forgotten that you put that test code in there.

Alternatives to MailHog

Of course, MailHog is not the only email testing tool around. Here are some alternatives (not tested)