MailHog Email Testing Server Management Skill

MailHog Email Testing Server Management

MailHog provides a comprehensive email testing solution for development and testing environments. This skill enables complete MailHog server management, email testing workflows, and integration with development pipelines.

Core Concepts

MailHog Architecture: MailHog consists of SMTP server (port 1025 by default) for receiving emails and HTTP API/UI (port 8025 by default) for viewing and managing captured emails.

Storage Options: Memory (default, ephemeral), MongoDB (persistent), or Maildir (file-based) for email storage.

Jim Simulation: Built-in chaotic network simulation for testing email resilience under adverse conditions.

Essential Setup Commands

Start Basic MailHog Server

Start MailHog with default settings (memory storage, ports 1025/8025):

# Basic start
mailhog

# Custom ports
mailhog -smtp-bind-addr :1025 -ui-bind-addr :8025 -api-bind-addr :8025

# Background execution
mailhog &

Start with Persistent Storage

Configure MongoDB storage:

mailhog -storage mongodb -mongo-uri 127.0.0.1:27017 -mongo-db mailhog_test -mongo-coll messages

Configure Maildir storage:

mailhog -storage maildir -maildir-path ./mail_storage

Configuration Management

Custom SMTP Configuration

# Custom hostname for EHLO/HELO
mailhog -hostname mailhog.test.local

# Custom bind addresses
mailhog -smtp-bind-addr 0.0.0.0:1025 -ui-bind-addr 0.0.0.0:8025

# CORS configuration
mailhog -cors-origin "http://localhost:3000,http://localhost:5173"

Authentication Setup

# Create bcrypt password file
echo "admin:$(bcrypt-hash 'password123')" > auth_file.txt

# Enable authentication
mailhog -auth-file auth_file.txt

Outgoing SMTP Configuration

Create outgoing SMTP configuration for email forwarding:

{
  "server": "smtp.gmail.com",
  "port": 587,
  "username": "test@gmail.com",
  "password": "app-password",
  "tls": true
}

mailhog -outgoing-smtp outgoing_config.json

Testing Email Functionality

Send Test Emails via CLI

Use built-in test utilities or SMTP clients:

# Using telnet for basic SMTP test
telnet localhost 1025
EHLO test.local
MAIL FROM:test@sender.local
RCPT TO:recipient@test.local
DATA
Subject: Test Email
From: test@sender.local
To: recipient@test.local

This is a test email.
.
QUIT

Send Test Emails with Scripts

Execute test email sending script:

./scripts/send_test_email.sh --to test@recipient.local --subject "Test Message" --body "Test content"

API Interaction Examples

Query captured emails via API:

# Get all messages
curl http://localhost:8025/api/v1/messages

# Get recent messages
curl http://localhost:8025/api/v1/messages?limit=10

# Search emails
curl -X POST http://localhost:8025/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query": "subject:test"}'

Development Integration

Environment Setup for Testing

Configure application environments for MailHog integration:

# Environment variables
export SMTP_HOST=localhost
export SMTP_PORT=1025
export SMTP_USER=
export SMTP_PASS=
export SMTP_TLS=false

Framework Integration Patterns

Node.js/Nodemailer Configuration:

const transporter = nodemailer.createTransporter({
  host: 'localhost',
  port: 1025,
  secure: false,
  auth: false
});

Python/SMTP Configuration:

import smtplib
server = smtplib.SMTP('localhost', 1025)
server.sendmail(sender, recipients, message)

Testing Workflow Automation

Execute automated testing script:

./scripts/test_email_workflow.sh --config test_config.json

Advanced Configuration

Network Simulation (Jim)

Enable Jim for chaotic network testing:

# Enable Jim with default settings
mailhog -invite-jim

# Custom Jim behavior
mailhog -invite-jim \
  -jim-accept 0.95 \
  -jim-reject-sender 0.1 \
  -jim-reject-recipient 0.1 \
  -jim-disconnect 0.02 \
  -jim-linkspeed-affect 0.2

Production-Ready Configuration

mailhog \
  -smtp-bind-addr 0.0.0.0:1025 \
  -ui-bind-addr 0.0.0.0:8025 \
  -api-bind-addr 0.0.0.0:8025 \
  -storage mongodb \
  -mongo-uri mongodb.example.com:27017 \
  -mongo-db mailhog_prod \
  -cors-origin "https://app.example.com" \
  -hostname mailhog.example.com

Monitoring and Debugging

Health Checks

Verify MailHog is running correctly:

# Check SMTP port
telnet localhost 1025

# Check UI/API
curl http://localhost:8025

# Check API status
curl http://localhost:8025/api/v1/messages

Log Analysis

Monitor MailHog operations and troubleshoot issues:

# Start with verbose logging (if available)
mailhog 2>&1 | tee mailhog.log

# Monitor message count
watch -n 5 'curl -s http://localhost:8025/api/v1/messages | jq ".total"'

Performance Optimization

Optimize for high-volume testing:

# Memory cleanup for long-running instances
curl -X DELETE http://localhost:8025/api/v1/messages

# MongoDB indexing for performance
# Execute via mongo shell on mailhog database
db.messages.createIndex({ "created": -1 })
db.messages.createIndex({ "From": 1 })

Common Workflows

Development Email Testing Setup

Start MailHog with appropriate configuration
Configure application SMTP settings to point to MailHog
Send test emails from application
Verify emails in MailHog UI (http://localhost:8025)
Use API for automated testing assertions

Automated CI/CD Integration

Include MailHog in test docker-compose or CI configuration
Configure test environment SMTP settings
Run application tests that send emails
Use API assertions to verify email content/delivery
Clean up messages between test runs

Bulk Email Testing

Use scripts to generate multiple test emails
Test rate limiting and performance
Verify email queue handling
Monitor resource usage during high-volume scenarios

Troubleshooting

Common Issues

Port Conflicts: Kill existing processes or change ports:

lsof -i :1025 -i :8025
kill -9 <PID>

MongoDB Connection Issues: Verify MongoDB is running and accessible:

mongo mongodb://127.0.0.1:27017/mailhog_test

Email Not Appearing: Check SMTP client configuration and network connectivity.

UI Not Loading: Verify API bind address and check for port conflicts.

Debug Commands

# Test SMTP connection manually
telnet localhost 1025

# Check MailHog process
ps aux | grep mailhog

# Verify API accessibility
curl -v http://localhost:8025/api/v1/messages

Security Considerations

Production Usage: Never expose MailHog directly to internet without authentication and proper firewall configuration.

Email Privacy: Captured emails may contain sensitive information - secure MailHog instance appropriately.

Authentication: Always use authentication in production environments with -auth-file.

Migration and Backup

MongoDB Backup

# Backup MailHog messages
mongodump --db mailhog_prod --collection messages --out ./backup

# Restore messages
mongorestore --db mailhog_prod --collection messages ./backup/messages.bson

Maildir Backup

# Backup maildir storage
tar -czf mailhog_maildir_backup.tar.gz ./mail_storage

Additional Resources

Reference Files

For detailed configurations and advanced patterns, consult:

references/configurations.md - Advanced configuration examples
references/api-endpoints.md - Complete API reference
references/integration-patterns.md - Framework integration guides

Scripts

Utility scripts for common operations:

scripts/send_test_email.sh - Send test emails via SMTP
scripts/test_email_workflow.sh - Automated testing workflow
scripts/mailhog_manager.sh - Server management utility

Examples

Working configurations and setups:

examples/docker-compose.yml - Docker container setup
examples/app-configs/ - Application configuration examples
examples/terraform/ - Infrastructure as code examples

Agent Skills: MailHog Email Testing Server Management

Install this agent skill to your local

Skill Files