MailHog with Docker Compose Setup Guide

This article targets development and QA environments. It shows how to run MailHog with Docker Compose and use it together with this temp inbox project to validate verification-code emails and notifications.

Use cases

• Receive emails in local dev without using a real mailbox.
• Validate outgoing emails in staging/CI (recipient, subject, content).
• Troubleshoot SMTP configuration issues.

What is MailHog?

MailHog is an email testing tool. It provides an SMTP server to accept messages and a Web UI / HTTP API to inspect them.

Quick setup (docker-compose)

If you use the repository docker-compose.yml, it typically already includes Redis, MailHog, and the app. Here is a minimal example for clarity:

services:
  mailhog:
    image: mailhog/mailhog:latest
    ports:
      - "25:1025"
      - "127.0.0.1:8025:8025"

  redis:
    image: redis:7-alpine

  app:
    image: node:20-alpine
    working_dir: /app
    environment:
      - MAILHOG_API=http://mailhog:8025
      - REDIS_URL=redis://redis:6379
    volumes:
      - ./app:/app
    command: node server.js

Start:

docker compose up -d

Endpoints

• MailHog Web UI: http://127.0.0.1:8025
• MailHog API (inside the network): http://mailhog:8025/api/v2/messages
• This project: http://127.0.0.1:3000

Point your app to MailHog SMTP

• Host: 127.0.0.1 (local) or mailhog (docker network)
• Port: 1025
• TLS/Auth: usually disabled for MailHog

FAQ

No emails received?

• Double-check SMTP host/port.
• Some VPS providers block port 25 by default.
• If MailHog UI has messages but the inbox website does not, verify MAILHOG_API.

Is MailHog for production?

MailHog is intended for testing. For production, use a real email service (SES/SendGrid/Mailgun, etc.).