GreenMail Email Server

GreenMail is a local email server used for development and testing. It captures all outbound emails without actually sending them, making it ideal for testing email functionality in the dev and stage environments.

The cluster documentation covers why stage uses a sink and how the SnappyMail configuration is generated: Mail Sink.

Overview

GreenMail provides:

SMTP server for sending emails
POP3 and IMAP servers for retrieving emails
REST API for programmatic access to messages
No authentication required (disabled for dev use)
No external dependencies

Kubernetes Deployment

GreenMail is deployed to the event-dev and event-stage namespaces using raw Kubernetes manifests (not a Helm chart). The stage manifests are copies of the dev ones; the examples below show dev.

Deployment Files

Located in the infrastructure repository under event-membership/greenmail-dev/ (and greenmail-stage/):

deployment.yml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: greenmail
  labels:
    app: greenmail
spec:
  replicas: 1
  selector:
    matchLabels:
      app: greenmail
  template:
    spec:
      containers:
      - name: greenmail
        image: greenmail/standalone:latest
        env:
        - name: GREENMAIL_OPTS
          value: '-Dgreenmail.hostname=0.0.0.0 -Dgreenmail.auth.disabled -Dgreenmail.smtp.port=25 -Dgreenmail.pop3.port=110 -Dgreenmail.imap.port=143 -Dgreenmail.api.port=8080'
        ports:
        - name: http
          containerPort: 8080
        - name: smtp
          containerPort: 25
        - name: pop3
          containerPort: 110
        - name: imap
          containerPort: 143

service.yml

apiVersion: v1
kind: Service
metadata:
  name: greenmail
spec:
  selector:
    app: greenmail
  type: ClusterIP
  ports:
    - name: http
      port: 8080
    - name: smtp
      port: 25
    - name: pop3
      port: 110
    - name: imap
      port: 143

ArgoCD Application

GreenMail is deployed via ArgoCD using a Git source (not OCI Helm):

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: greenmail-dev
  namespace: argocd
spec:
  project: default
  destination:
    name: idl-xnl-jhb1-rc01
    namespace: event-dev
  source:
    repoURL: [email protected]:christhonie/idl-xnl-jhb-rc01.git
    targetRevision: HEAD
    path: event-membership/greenmail-dev
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Exposed Ports

Port Protocol Purpose

Port	Protocol	Purpose
25	SMTP	Send emails
110	POP3	Retrieve emails (POP3 protocol)
143	IMAP	Retrieve emails (IMAP protocol)
8080	HTTP	REST API, with a Swagger UI at `/`

SMTP

Send emails

110

POP3

Retrieve emails (POP3 protocol)

143

IMAP

Retrieve emails (IMAP protocol)

8080

HTTP

REST API, with a Swagger UI at /

Integrating with Applications

Kubernetes Service DNS

Within the cluster, applications connect to GreenMail using its service DNS name:

greenmail.event-dev.svc.cluster.local
greenmail.event-stage.svc.cluster.local

Application Configuration

Configure Spring Boot applications to use GreenMail in dev deployments:

ArgoCD valuesObject (example from registration-portal)

config:
  mail:
    host: greenmail.event-dev.svc.cluster.local
    port: 25
    from: [email protected]
    username: ""
    password: ""
    protocol: smtp
    tls: false
    properties.mail.smtp:
      auth: false
      starttls.enable: false

Key settings:

No authentication: username and password are empty, auth: false
No TLS: tls: false and starttls.enable: false
Standard SMTP port: Port 25 (GreenMail configured with -Dgreenmail.smtp.port=25)

Viewing Captured Emails

REST API

GreenMail provides a REST API on port 8080 for accessing captured messages. The full specification is served at /greenmail-openapi.yml, and browsable at /.

Messages are reachable only per mailbox. There is no endpoint listing every message — /api/mail returns 404.

List every mailbox that has received something

curl http://greenmail.event-dev.svc.cluster.local:8080/api/user

Get the messages in one mailbox (subject, recipients, full MIME)

curl http://greenmail.event-dev.svc.cluster.local:8080/api/user/[email protected]/messages
# Another folder, e.g. the Sent folder SnappyMail keeps
curl http://greenmail.event-dev.svc.cluster.local:8080/api/user/[email protected]/messages/Sent

Delete every message

curl -X POST http://greenmail.event-dev.svc.cluster.local:8080/api/mail/purge

Port Forwarding for Local Access

To access GreenMail from your local machine:

kubectl port-forward -n event-dev svc/greenmail 8080:8080 25:25

Then access the API at http://localhost:8080/api/user.

Mail Sent by EMS Services

The EMS services submit mail over plain SMTP, which has no concept of a sent folder, and GreenMail delivers only to the envelope recipients. A message a service sends therefore appears in each recipient’s mailbox and nowhere else — the sender’s Sent stays empty.

To check what a service sent, open the recipient’s mailbox in SnappyMail or query it through the API.

Common Issues

Connection Refused

Verify GreenMail pod is running: kubectl get pods -n event-dev -l app=greenmail
Check pod logs: kubectl logs -n event-dev -l app=greenmail
Ensure correct service DNS name is used

Authentication Errors

GreenMail is configured with -Dgreenmail.auth.disabled. If you see authentication errors:

Verify application config has auth: false
Ensure username and password are empty strings, not null
Check starttls.enable: false is set

Emails Not Captured

Verify SMTP port 25 is being used (not 587 or 465)
Check application logs for SMTP connection errors
Test connectivity: kubectl exec -n event-dev <pod> — nc -zv greenmail 25

SnappyMail Web Client

SnappyMail is a lightweight, modern web-based email client deployed alongside GreenMail for viewing and composing test emails.

Overview

SnappyMail provides:

Web-based email interface for IMAP/SMTP
Access to any mailbox GreenMail holds, on any domain (no pre-registration required)
Compose and send test emails, with sent mail kept in the sender’s Sent folder
View emails received by any address, including customer addresses on stage

Kubernetes Deployment

SnappyMail is deployed to the event-dev and event-stage namespaces using raw Kubernetes manifests.

Deployment Files

Located in the infrastructure repository under event-membership/snappymail-dev/ (and snappymail-stage/):

configmap.yml - Start-up script pointing every domain at GreenMail, and the greenmail-folders plugin
deployment.yml - SnappyMail container deployment
service.yml - ClusterIP service on port 8888
ingress.yml - Public hostname with a Let’s Encrypt certificate
pvc.yml - Longhorn volume for SnappyMail’s data directory

ArgoCD Application

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: snappymail-dev
  namespace: argocd
spec:
  project: default
  destination:
    name: idl-xnl-jhb1-rc01
    namespace: event-dev
  source:
    repoURL: [email protected]:christhonie/idl-xnl-jhb-rc01.git
    targetRevision: HEAD
    path: event-membership/snappymail-dev

Accessing SnappyMail

Web

Environment	URL
Dev	https://event-mail-dev.idealogic.co.za
Stage	https://event-mail-stage.idealogic.co.za

Environment

URL

Dev

https://event-mail-dev.idealogic.co.za

Stage

https://event-mail-stage.idealogic.co.za

Port Forwarding

If the ingress is unavailable, reach SnappyMail from your local machine directly:

kubectl port-forward -n event-dev svc/snappymail 8888:8888

Then open http://localhost:8888 in your browser.

Kubernetes Service DNS

Within the cluster, SnappyMail is accessible at:

snappymail.event-dev.svc.cluster.local:8888

Logging In

Sign in with any email address, on any domain, and any passphrase — GreenMail has authentication disabled, and SnappyMail sends every domain to it. There is nothing to select or pre-register.

To see what a customer received, sign in as the customer’s address (e.g. [email protected]).
To act as the organisation, sign in as the sending address (e.g. [email protected] on stage).

GreenMail creates a mailbox the first time an address receives mail or signs in, so an address that has received nothing opens to an empty inbox.

On each sign-in, SnappyMail creates any missing Sent, Drafts, Junk, Trash and Archive folders and maps them, because GreenMail provides only INBOX.

GreenMail keeps mail and folders in memory. After it restarts, every mailbox is empty and the folders are gone until you sign out and back in.

Sending Test Emails

Use SnappyMail to compose and send emails between test accounts:

Log in as one user (e.g., [email protected])
Compose an email to another address (e.g., [email protected])
Send the email (captured by GreenMail); a copy is kept in the sender’s Sent
Log out and log in as [email protected] to view the received email

Mail sent by the EMS services is not kept in the sender’s Sent — see Mail Sent by EMS Services.

Admin Panel

SnappyMail includes an admin panel for configuration:

URL: the SnappyMail address with ?admin appended, e.g. https://event-mail-dev.idealogic.co.za/?admin
Username: admin
Password: generated on first start and stored in /var/lib/snappymail/data/default/admin_password.txt inside the pod

The admin panel is primarily for troubleshooting. Configuration is managed via the ConfigMap, and the start-up script rebuilds the domain configuration on every restart, so domain changes made in the admin panel do not survive.

Common Issues

Cannot Connect to Mail Server

Verify GreenMail pod is running: kubectl get pods -n event-dev -l app=greenmail
Check SnappyMail logs: kubectl logs -n event-dev -l app=snappymail
Ensure GreenMail service is accessible from SnappyMail pod

Login Fails

GreenMail should have authentication disabled (-Dgreenmail.auth.disabled)
Any password should work; try a simple one like test
Can’t connect to host "tcp://localhost:143" means the domain resolved to SnappyMail’s seeded default.json instead of GreenMail. The start-up script removes that file; check the pod started cleanly, and restart it to re-run the script

"Select system folders" When Sending

The folders were not created at sign-in — typically because GreenMail restarted during the session. Sign out and back in.

No Emails Visible

Emails only appear after being received by GreenMail, and a GreenMail restart discards them
Check that you’re logged in as the recipient — mail sent by an EMS service is not in the sender’s mailbox
Confirm the message reached GreenMail through the API: curl http://greenmail:8080/api/user/<address>/messages