Jens Knipper

Manually testing email notifications with GreenMail mock mail server

February 16, 2021 | 4 Minute Read

A re you sending mails featured with HTML and CSS and want see how they look before pushing your changes to production? You also do not want mails to leak from your local environment to your customer? A mock mail server like GreenMail might just be the tool you need.

Whenever developing an application I aim to get local and testing environment as close to production as possible without neglecting elementary things like privacy and security. This gives an advantage when implementing new features. You get the same user experience on your local device. This enables you to find troublesome or unclear sections.
It also lowers the barrier for manual testing, which results in more and higher quality feedback from everyone (not only developers) involved in the project.

For testing purposes you usually do not want to connect to production systems. That is why local or test environments often use local instances of additional applications like a database. This can also be applied to a mail server. When executing a local instance of a mail server you have to configure it properly to avoid leakage of data to your customers. A mock mail server like GreenMail is built to keep data on the same machine thus serves as a good option.

To use GreenMail as a mail server you should use the standalone version. Running it in a docker container is the simplest approach.

version: '3'

services:
  greenmail:
    image: "greenmail/standalone"
    environment:
      - JAVA_OPTS=-Dgreenmail.verbose
    ports:
      - 3025:3025 # SMTP
      - 3110:3110 # POP3
      - 3143:3143 # IMAP
      - 3465:3465 # SMTPS
      - 3993:3993 # IMAPS
      - 3995:3995 # POP3S

There are a few environment variables you can set to configure GreenMail. A good option is setting the logging to verbose. This way you can identify misconfigurations easily.
All of the most common mail protocols are supported. The ports have an offset of 3000 compared to the default port of the corresponding protocol. That’s it, you are now able to use GreenMail in your application.

To test your mails locally you can either connect to a desktop client like Thunderbird or install a web client. A simple but popular web client is Roundcube. In this example running it in a docker container is also the simplest approach.

  roundcube:
    image: roundcube/roundcubemail
    depends_on:
      - greenmail
    ports:
      - 8000:80
      - 9000:9000
    environment:
      - ROUNDCUBEMAIL_DEFAULT_HOST=greenmail  # IMAP server - tls:// prefix for STARTTLS
      - ROUNDCUBEMAIL_DEFAULT_PORT=3143       # IMAP port
      - ROUNDCUBEMAIL_SMTP_SERVER=greenmail   # SMTP server - tls:// prefix for STARTTLS
      - ROUNDCUBEMAIL_SMTP_PORT=3025          # SMTP port

To make Roundcube use GreenMail you habe to specify certain environment variables for the Roundcube container.
You can read mails using the IMAP or POP3 protocol. You just need to specify the url and the port. Writing mails can be done using the SMTP protocol where you also have to specify the url and the proper port.

GreenMail automatically accepts all incoming mails. If there is no corresponding address, one will automatically be created. The password is equal to the mail address.
Because of this you should not make the GreenMail and Roundcube instances publicly available. If you still want to integrate it in your test or staging environment it is highly recommended to secure it with a reverse proxy like nginx or Traefik.

Further readings

You can check out the whole configuration on GitHub. There is also a small example application where you can test the described behaviour in action.