mailhog-testing

Overview

Per github.com/mailhog/MailHog:

"MailHog is an email testing tool for developers" that allows you to "Configure your application to use MailHog for SMTP delivery" and "View messages in the web UI, or retrieve them with the JSON API."

MailHog is legacy as of the mid-2020s - Mailpit (per mailpit-testing) succeeded it with richer API + active maintenance. This skill covers MailHog for existing deployments + provides migration guidance to Mailpit.

When to use

• Existing MailHog deployment that the team isn't ready to migrate.
• A specific MailHog feature behaves differently than Mailpit's equivalent (rare; investigate before assuming MailHog-specific behavior is required).
• Tests already wired against MailHog's APIv2 + the team needs to document what the tests do before migration.

For new projects, use mailpit-testing.

Step 1 - Install

Per mh-gh:

# Go install
go install github.com/mailhog/MailHog@latest

Docker:

docker run -d \
  --name mailhog \
  -p 1025:1025 \
  -p 8025:8025 \
  mailhog/mailhog

Step 2 - Default ports

Per mh-gh:

Step 3 - Configure your app's SMTP

Same pattern as Mailpit (since both expose unauthenticated SMTP on 1025 by default):

smtp:
  host: localhost
  port: 1025
  auth: none

Step 4 - Assert via APIv2

Per mh-gh MailHog has both APIv1 + APIv2; APIv2 is the modern one. Endpoints:

Test pattern:

import requests

BASE = "http://localhost:8025"

def test_password_reset_via_mailhog():
    requests.delete(f"{BASE}/api/v1/messages")
    trigger_password_reset("alice@example.com")
    msg = poll_for_message(BASE, to="alice@example.com")

    assert msg["Content"]["Headers"]["Subject"][0] == "Reset your password"
    assert "/reset?token=" in msg["Content"]["Body"]

The MailHog message structure is more nested than Mailpit's (Content.Headers.Subject array vs Mailpit's flat Subject field).

Step 5 - Jim chaos monkey

Per mh-gh: "Chaos Monkey for failure testing" via the Jim component. Jim is configurable via CLI flags or environment:

mailhog -invite-jim   # enables the chaos monkey

Once Jim is invited, MailHog injects failures (random connection drops, slow responses) per the configured probabilities. Configuration flags are documented in mailhog -h; the README references "Introduction to Jim" for details.

For new test work needing chaos, prefer Mailpit's Chaos mode (per mailpit-testing Step 5) - it has richer per-recipient configuration.

Step 6 - CI integration

services:
  mailhog:
    image: mailhog/mailhog
    ports: [1025:1025, 8025:8025]

steps:
  - run: pytest tests/integration/email/ -v

Step 7 - Migration to Mailpit

Side-by-side feature mapping:

Migration steps:

1. Stand up Mailpit alongside MailHog (different ports temporarily).
2. Update test code to hit Mailpit's endpoints + flatter schema.
3. Run both in CI parallel for one PR cycle.
4. Cut over.

Anti-patterns

Limitations

• MailHog has not had significant new releases since ~2020; unmaintained for new features.
• APIv2 is the modern API but APIv1 is required for the message-clear operation (no APIv2 equivalent); awkward inconsistency.
• Jim chaos-monkey configuration is less rich than Mailpit's Chaos mode.
• Some Docker images on Docker Hub may be unmaintained; verify the pulled image was built recently.

References

• mh-gh - repository
• mailhog/MailHog APIv2 docs - github.com/mailhog/MailHog/blob/master/docs/APIv2.md
• mailpit-testing - successor; preferred for new projects
• email-flow-test-author - build-an-X for the full email-sending workflow (works with either Mailpit or MailHog)