MailHog

beginner

Email testing tool for development.

Overview

MailHog is a web and API-based SMTP testing service designed specifically for development environments. Created by Ian Kent, MailHog acts as an email catcher that intercepts all outbound emails from your applications, displaying them in a clean web interface instead of delivering them to real recipients. This prevents accidental email sends during development while allowing developers to test email functionality thoroughly. This Docker deployment creates a complete email testing environment with MailHog running as a single service. The SMTP server listens on port 1025 to capture emails from your applications, while the web interface on port 8025 provides real-time viewing and management of all intercepted messages. MailHog stores emails in memory, making it perfect for development workflows where you need quick email testing without database overhead. Development teams, QA engineers, and individual developers will find this setup invaluable when building applications with email features. Unlike production email services or complex testing frameworks, MailHog provides immediate visual feedback for email templates, content, and delivery logic without requiring external email accounts or risking spam filters during development cycles.

Key Features

SMTP server on port 1025 captures all outbound emails from applications without external delivery
Web-based email viewer at port 8025 displays messages with full HTML rendering and attachment support
RESTful API at /api/v2 endpoint enables programmatic email retrieval and automated testing integration
Real-time email search and filtering by sender, recipient, subject, or message content
Message storage in memory with automatic cleanup on container restart for clean testing sessions
JSON and raw message format viewing for debugging email headers and MIME structure
Multi-part message support showing both HTML and plain text versions side-by-side
Zero-configuration email catching that works with any SMTP-compatible application or framework

Common Use Cases

1Testing user registration and password reset email workflows during web application development
2Validating email templates and HTML rendering across different email clients without sending real emails
3Debugging SMTP integration issues in microservices or monolithic applications during local development
4Quality assurance testing of notification systems without cluttering real inboxes or triggering spam filters
5Demonstration environments where email functionality needs to work but external delivery is unwanted
6Integration testing of e-commerce order confirmations and shipping notifications in development pipelines
7Educational environments where students learn email integration without requiring real email infrastructure

Prerequisites

Docker and Docker Compose installed with at least 512MB available memory for the MailHog container
Ports 1025 and 8025 available on the host system for SMTP and web interface access
Basic understanding of SMTP configuration to point applications to localhost:1025 for email sending
Network connectivity between your application containers and the MailHog container if running in Docker networks
Web browser access to localhost:8025 for viewing the MailHog web interface and captured emails

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  mailhog: 
3    image: mailhog/mailhog:latest
4    container_name: mailhog
5    restart: unless-stopped
6    ports: 
7      - "1025:1025"
8      - "8025:8025"

.env Template

.env

1# SMTP on port 1025, Web UI on 8025

Usage Notes

1Docs: https://github.com/mailhog/MailHog
2Web UI at http://localhost:8025 - view caught emails
3SMTP server on port 1025 - configure apps to send here
4All emails caught locally, never delivered externally
5API available at /api/v2 for programmatic access
6Search emails by content, sender, recipient

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  mailhog:
5    image: mailhog/mailhog:latest
6    container_name: mailhog
7    restart: unless-stopped
8    ports:
9      - "1025:1025"
10      - "8025:8025"
11EOF
12
13# 2. Create the .env file
14cat > .env << 'EOF'
15# SMTP on port 1025, Web UI on 8025
16EOF
17
18# 3. Start the services
19docker compose up -d
20
21# 4. View logs
22docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/mailhog/run | bash

Troubleshooting

Emails not appearing in MailHog interface: Verify your application is configured to use localhost:1025 as SMTP server with no authentication
Connection refused on port 1025: Check if another service is using the port with 'netstat -tlnp | grep 1025' and modify port mapping if needed
MailHog web interface not loading: Ensure port 8025 is not blocked by firewall and container is running with 'docker logs mailhog'
Container exits immediately on startup: Check Docker logs for permission errors and ensure the mailhog user can bind to the configured ports
Memory issues with large email volumes: Restart the MailHog container to clear in-memory storage as it doesn't persist emails between restarts
CORS errors when accessing API: MailHog API allows cross-origin requests by default, but check browser network tab for specific CORS policy violations

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

mailhog

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download