MailCatcher

When to use?

When you're working as a developer or tester on an application that sends out emails, you want to prevent that mails end up in production environments, or worse, at actual clients.

So when you are testing an email functionality inside an application, this container can be of use to catch the mail so you can see what's supposed to be sent out.

How to use?

To use this container, simply add the following service to your docker-compose.yaml:

services:
  mailcatcher:
    image: garrcomm/mailcatcher
    ports:
      - "127.0.0.1:25:25"
      - "127.0.0.1:465:465"
      - "127.0.0.1:80:80"

All mails delivered to this container at port 25 (SMTP) or 465 (SSMTP) will be available through the webinterface at port 80 (HTTP).

If you're application is also in the same Docker Compose project, you can deliver its mails to mailcatcher:25 and port 25 doesn't need to be exposed outside of the project network.

Additional service options

You can even go a bit further in the service declaration in your docker-compose.yaml file. This example shows some varieties:

services:
  mailcatcher:
    image: garrcomm/mailcatcher
    volumes:
      - ./examples/mails:/var/smtpserver:cached
    environment:
      BASE_HREF: /mailcatcher/
    ports:
      - "127.0.0.1:25:25"
      - "127.0.0.1:465:465"
      - "127.0.0.1:80:80"

• The volumes entry
  When defined, the folder ./examples/mails in the host OS will contain the .eml files. This can be useful to get easy access to the email files.
• The BASE_HREF entry
  If you use a proxy where the base href changes, you can overrule it there. Keep in mind, it should always end with a /. A use case can be if you're using a traefik, nginx or other proxy container that changes the URL.

Sendmail drop-in

A lot of applications, mostly Unix based, use sendmail to deliver mails. This package provides a drop-in replacement that delivers mail to an SMTP server instead.

In, for example, PHP, you can configure this by adding this in the php.ini:

sendmail_path = "/absolute/path/to/mcsendmail.sh -t -i"

When the server name or port number is different, try;

sendmail_path = "/absolute/path/to/mcsendmail.sh -t -i -Shostname:portnumber"

It's also possible to set the environment values SMTP_HOSTNAME and SMTP_PORT instead of using the -S parameter.

All available command line arguments of mcsendmail.sh explained:

-f[mail-address]   Sets the name of the 'from' person (i.e., the envelope sender of the mail).
-V[envelope-id]    Set the original envelope id.
-S[host:port]      Defines the SMTP host and port to connect to.
-t                 Read message for recipients. The Bcc: line will be deleted before transmission.
-i                 Ignore dots alone on lines by themselves in incoming messages.
-r[mail-address]   An alternate and obsolete form of the -f flag.

Set up when you want to develop on the MailCatcher itself

In the root is a docker-compose.yaml which is made for development purposes. When bringing up the environment by docker compose up -d it's possible to run this locally.

To send an email, execute one of the examples, or execute them all by running bin/run-all-examples.sh or bin/run-all-examples.bat. The result should end up in the examples/mails folder and in the web interface. To go to the web interface, open http://localhost/.

Most files are available immediately after a change, but if a config file is changed, it's possible you need to restart the container by docker compose restart mailcatcher. If you modify the Dockerfile you also need to rebuild the container by docker compose build mailcatcher.

To fetch all dependencies for the web application, execute:

bin/composer.sh install

To publish the container, execute bin/update.sh or bin/update.bat.

Todo

• Add authentication on web interface and smtp interface?
• Look into custom SSL certificates