Mailcatcher

Troubleshoot SMTP using Mailcatcher Docker Image

4 min readMar 14, 2022

Emails are mission critical for your app and you need a simple way to make sure that they are triggered on time and properly formatted. This is where mailcatcher enters into action.

About Mailcatcher:

website: mailcatcher.me

Mailcatcher is a minimalistic SMTP server that you will set up while developing or testing. It captures the emails your application is sending and will renders them in a web interface.

When developing or testing, set your app to deliver to smtp://127.0.0.1:1025, then check out http://127.0.0.1:1080 to see the mail that’s arrived so far. Caveat: you might need to change the IP address… but you got the idea.

As a bonus, if your application uses websockets the emails will render instantly, otherwise you will have to wait for 30 seconds for the interface to refresh.

Mailcatcher key features:

Control how many recent emails are preserved in Mailcatcher.
Download the emails from Mailcatcher and open them in a different mail client.

Why dockerizing Mailcatcher?

Well, before using Mailcatcher you need to have Ruby installed on your computer and there are many situations where either you do not want to or cannot.

This is why packaging Mailcatcher in a docker image makes sense.

The Dockerfile supporting this project can be found on GitHub: https://github.com/spaquet/docker-alpine-mailcatcher

There are 3 main ways to use the docker image:

From GitHub
From Dockerhub
Via a Docker Compose

Why using Alpine Linux?

Well, that’s pretty straightforward: the image is very small. The compressed size is about 14M and once installed on your environment the image remains under 40M.

Let’s get started!

From GitHub

The main advantage of this approach is that you can edit the Dockerfile and customize the image to your needs.

Open a Terminal and run the following command to “download” the latest code from GitHub:git clone git@github.com:spaquet/docker-alpine-mailcatcher.git

Then go to the docker-alpine-mailcatcher directory and start the container by typing the following command:

docker run --rm -it -p 1080:1080 -p 1025:1025 --name mailcatcher $(docker build -q .)

This will build the docker image from the local Docker file and run it. After you are done using it the image is removed from your system thanks to the--rm flag.

The -p 1080:1080 command is used to map the exposed port to a local port on your system. If omitted docker will select for you a local port to be used. But given our use case it is better to always use the same ports (web and smtp).

From Dockerhub

The easy peasy way 😎.

Open a Terminal and run the following command docker pull stpaquet/alpinemailcatcher This will install the latest image on your computer.

docker images should return something similar to

Now that the image is installed, you can launch it using commands such as these ones:

docker run --rm -p 1080:1080 -p 1025:1025 --name mailcatcher stpaquet/alpinemailcatcheror to run it as a deamon:docker run -d -p 1080:1080 -p 1025:1025 --name mailcatcher stpaquet/alpinemailcatcher

Note: you can actually skip the docker pull step as calling docker run will install the image on your computer if it is not already installed.

Passing environment variables

This image accepts several variable that can be passed at run time. The most important ones are TIMEZONE and MAIL_LIMIT

TIMEZONE accept Linux format time zones such as Europe/Paris or America/Los_Angeles. By default the image is set to UTC.

MAIL_LIMIT expect a number to control the number of emails to be kept in Mailcatcher. The default value is set to 50.

Passing different value at run time is done using the -e flag.

Examples:

Increase to 60 the number of emails kept in Mailcatcher:

docker run -d -p 1080:1080 -p 1025:1025 -e MAIL_LIMIT=60 ...

Change the timezone to be Los Angeles

docker run -d -p 1080:1080 -p 1025:1025 -e TIMEZONE=Los_Angeles ...

Using Docker Compose

As apps are using different service it is current to launch and connect them all together via docker compose.

Here is an example of a docker-compose.yml file:

version: "3.9"services:  mailcatcher:
    container_name: mailcatcher
    restart: on-failure:10
    image: stpaquet/alpinemailcatcher:latest
    environment:
      - MAIL_LIMIT=70 # docker image default is 50
      - TIMEZONE=America/Los_Angeles # docker image default is UTC
    ports:
      - "1080:1080"
      - "1025:1025"

Calling docker-compose up will start Mailcatcher.