# MailHog

> Email testing tool for development.

- Category: Development Tools
- Difficulty: beginner
- Components: mailhog
- Tags: mailhog, email, testing, smtp
- Source: https://docker.recipes/development/mailhog

## 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.

## 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

## Use cases

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

## docker-compose.yml

```yaml
services:
  mailhog:
    image: mailhog/mailhog:latest
    container_name: mailhog
    restart: unless-stopped
    ports:
      - "1025:1025"
      - "8025:8025"
```

## .env

```bash
# SMTP on port 1025, Web UI on 8025
```

## Usage notes

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

## 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

