garrcomm/mailcatcher repository overview

⁠MailCatcher Docker container

The purpose of this container is to catch mails instead of sending them out to the internet while testing (web) applications that should send out emails. It's made by Stefan Thoolen⁠.

⁠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:80:80"

All mails delivered to this container at port 25 (SMTP) 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: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.

⁠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 php-manual-mail-example-5.bat⁠ or php-manual-mail-example-5.sh⁠ depending on your operating system. The result should end up in the mails⁠ folder. 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 work on the web interface, see also it's own README.md⁠.

To publish the container, execute update.sh⁠ or update.bat⁠.

⁠Todo

• Refactor server.php⁠
• Add authentication on web interface and smtp interface?