mwaeckerlin/fake-smtp repository overview

⁠fake-smtp

A minimal fake SMTP server for testing. Accepts all incoming mails without sending them anywhere — stores each message as a plain-text file and logs all SMTP traffic.

⁠Purpose

Use fake-smtp wherever your stack sends outgoing email during development or CI:

• Verify that your application actually sends an email (and to whom)
• Inspect the full raw message (headers + body) without a real MTA
• Test SMTP integration of services like mailservice⁠ end-to-end

⁠Quick Start

npm start          # foreground with logs
npm run start:daemon  # background

Then send a test mail:

swaks --to [email protected] --from [email protected] \
      --server localhost --port 2525

Or with plain netcat:

{ echo -e "EHLO test\r\nMAIL FROM:<[email protected]>\r\nRCPT TO:<[email protected]>\r\nDATA\r\nSubject: hi\r\n\r\nBody\r\n.\r\nQUIT\r\n"; sleep 1; } \
  | nc localhost 2525

⁠What It Does

• Listens on port 25 inside the container (mapped to FAKE_SMTP_PORT, default 2525)
• Accepts every MAIL FROM / RCPT TO without authentication or TLS
• On DATA: writes the full raw message to /mails/<timestamp>-<from>-<to>.txt
• Logs every SMTP command and response to /mails/log and stderr
• Supports: EHLO, HELO, MAIL FROM, RCPT TO, DATA, QUIT
• Does not support: AUTH, STARTTLS, extensions

⁠Inspecting Received Mails

# list received mails
docker compose exec fake-smtp ls /mails/

# read a mail
docker compose exec fake-smtp cat /mails/<filename>

# tail the SMTP log
docker compose exec fake-smtp tail -f /mails/log

# or mount the volume on the host and access directly

⁠Configuration

⁠Using in docker-compose

Point any service that sends mail to fake-smtp:25:

services:
  fake-smtp:
    image: mwaeckerlin/fake-smtp
    ports:
      - "${FAKE_SMTP_PORT:-2525}:25"
    volumes:
      - mails:/mails

  myapp:
    image: myapp
    environment:
      SMTP_HOST: fake-smtp
      SMTP_PORT: 25

volumes:
  mails:

⁠End-to-End Testing with mailservice

Replace the outbound relay with fake-smtp to capture mails sent by postfix/mailforward without a real internet connection:

services:
  smtp-relay:
    image: mwaeckerlin/fake-smtp   # swap real relay
    networks:
      - relay-net

  fake-smtp:
    image: mwaeckerlin/fake-smtp
    volumes:
      - mails:/mails
    networks:
      - relay-net

Then in your test:

1. Trigger an action that causes the application to send an email
2. Wait for a file to appear in /mails/
3. Assert filename (recipient), headers, and body content