MailHog

Update - 5th Dec 2024

It appears that MailHog is no longer being maintained. One may wish to look at Mailpit instead, and I will put a link here once I have a tutorial for it.

Introduction

MailHog is a free and open source (GitHub) email-testing tool with a fake SMTP server underneath. It is designed for developers, allowing them to test an applications email sending capability without needing to hook up to a real SMTP server. The developers can go into the MailHog web UI to view all of the sent emails. This also means that you can test an application without the risk of "real" emails going out to actual people.

Demonstration Codebase

For this tutorial, I created an example codebase on GitHub to allow you to quickly deploy Mailhog with an emailer application that sends a test email once every three seconds. Below is the docker-compose.yml file for quick reference if you just want to see how the MailHog service is defined, so you can quickly get it configured within your application:

Docker Compose File

version: "3.9"

services:
  app:
    build:
      context: .
      dockerfile: ./Dockerfile
    container_name: emailer
    image: mailhog-emailer
    depends_on:
        - mailhog
    environment:
      - SMTP_HOST=mailhog
      - SMTP_USER=null
      - SMTP_PASSWORD=null
      - SMTP_PORT=1025
      - SMTP_PROTOCOL=none
      - SMTP_FROM_EMAIL=myapp@gmail.com
      - SMTP_FROM_NAME=myAppName
      - MAIL_TO_EMAIL=myemail@gmail.com
      - MAIL_TO_NAME=My Name


  # Mailhog fake SMTP server
  # https://github.com/mailhog/MailHog
  mailhog:
    container_name: mailhog
    image: mailhog/mailhog:v1.0.1
#    Uncomment the logging lines below if you need to disable logging
#    logging:
#      driver: 'none'  # disable saving logs
    ports:
        - 1025:1025 # smtp server
        - 8025:8025 # web ui

As you can see from the service definition, it is extremely easy to set up and configure with not requiring any environment variables or volumes needing to be set up.

Build and Run

docker-compose build
docker-compose up

Then you can view the generated emails at http://localhost:8025/

Adding Authentication

Most people will be deploying MailHog locally on a computer for testing emails in development. However, if you are deploying a central MailHog server for other users to use, then you probably want to add some basic authentication. Luckily this can be done by adding an htpasswd file that we inject through a volume and updating the entrypoint as shown in the Docker compose file example below:

services:

  mailhog:
    container_name: mailhog
    image: mailhog/mailhog:v1.0.1
    ports:
        - 1025:1025 # smtp server
        - 8025:8025 # web ui
    volumes:
        - ./auth.txt:/auth.txt:ro
    entrypoint: "MailHog -auth-file=/auth.txt"

Obviously this requires you to have created an htpasswd file with the name auth.txt here. For this you can use the hpasswd tool (installed with the apache2-utils package on Debian/Ubuntu) like so:

USERNAME="myUsername"
PASSWORD="myPassword"

htpasswd -Bbn $USERNAME $PASSWORD > ./auth.txt

The -B tells htpasswd to use bcrypt hashing, which is what MailHog requires.

References

• MailHog - Authentication