mailpit-testing

Email is the most underspecified surface in modern web apps. A "the email got sent" assertion misses:

• Did the user receive both HTML + plain-text alternatives? (RFC 2046 §5.1.4 multipart/alternative)
• Was the link in the email actually correct (after tracking rewrites)?
• Did the unsubscribe link work?
• For relayed messages: do DKIM / SPF / DMARC pass?
• Does the app handle bounces + complaints?

This is a build-an-X workflow - a checklist and per-stage test recipes, not a single tool. The SMTP capture layer is the host SKILL.md (Mailpit) or mailhog-legacy.md (opens in new window).

When to use

• Any feature triggers a transactional email (signup, password reset, order confirmation, account notification).
• Marketing-email integration with the app needs regression coverage.
• Compliance review requires evidence of unsubscribe + bounce handling.

Step 1 - Stage your capture environment

Per the host SKILL.md:

# CI config
services:
  mailpit:
    image: axllent/mailpit:v1.20.0
    ports: [1025:1025, 8025:8025]

Configure the app to relay via this SMTP for the test environment.

Step 2 - Trigger + capture

from email_test_helpers import trigger_password_reset, capture_one_email

def test_password_reset_email_complete():
    msg = capture_one_email(
        action=lambda: trigger_password_reset("alice@example.com"),
        recipient="alice@example.com",
        timeout=5,
    )
    # Now assert against `msg`

(capture_one_email is the helper from the host SKILL.md Step 4.)

Step 3 - Header assertions

def test_email_headers(msg):
    assert msg["From"]["Address"] == "noreply@example.com"
    assert msg["To"][0]["Address"] == "alice@example.com"
    assert msg["Subject"] == "Reset your password"
    assert "List-Unsubscribe" in msg["Headers"]    # required by Gmail/Yahoo bulk-sender rules
    assert "List-Unsubscribe-Post" in msg["Headers"]   # one-click unsubscribe per RFC 8058

For relayed-via-MTA tests (where DKIM signing happens), additional checks:

• DKIM signature present + valid
• SPF-aligned Return-Path
• DMARC-aligned From

These checks require a relay capable of signing (production MTA or a test-relay like Postmark sandbox). Mailpit doesn't sign; verify DKIM in a separate staging-with-real-MTA test layer.

Step 4 - Body content assertions

Email is multipart: HTML and plain-text alternatives. Both need verification:

def test_email_body_alternatives(msg):
    # Plain-text body present
    assert msg["Text"]
    assert "alice" in msg["Text"]
    assert "/reset?token=" in msg["Text"]

    # HTML body present + matches plain-text intent
    html = msg["HTML"]
    assert "<a href=" in html
    assert "/reset?token=" in html

    # The "view in browser" link
    assert ("/view-in-browser/" in html) or ("This email best viewed" in html)

Per RFC 2046 §5.1.4, mailers should always include a plain-text alternative; tests catch when developers ship HTML-only emails by accident.

Step 5 - Link rewriting + tracking pixels

Many email service providers (Mailgun, SendGrid, Postmark, Customer.io) rewrite links for click tracking. After rewriting, the link in the captured email points to the ESP's tracker, not the target URL.

Test pattern: assert against the final URL after redirect, not the rewritten one:

import requests

def resolve_redirects(url, max_hops=5):
    for _ in range(max_hops):
        response = requests.get(url, allow_redirects=False, timeout=5)
        if response.status_code not in (301, 302, 303, 307, 308):
            return response.url
        url = response.headers["Location"]
    raise ValueError("Too many redirects")

def test_password_reset_link_resolves_to_app(msg):
    link = extract_first_link(msg["HTML"])
    final_url = resolve_redirects(link)
    assert "example.com/reset" in final_url
    assert "token=" in final_url

For tests of unsigned ESP links, accept the rewrite as expected and test that resolution lands on the app's domain.

Step 6 - Unsubscribe-link verification

def test_unsubscribe_link_works(msg):
    unsubscribe_url = msg["Headers"]["List-Unsubscribe"][0].strip("<>")
    response = requests.post(unsubscribe_url)
    assert response.status_code == 200

    # Verify the user is now unsubscribed:
    user = User.objects.get(email="alice@example.com")
    assert user.subscribed is False

Per RFC 8058, one-click unsubscribe is a POST (not GET) to the List-Unsubscribe URL with body List-Unsubscribe=One-Click.

Step 7 - Bounce + complaint handling

Bounces (delivery failures) and complaints (recipient marks as spam) come from the ESP via webhook. Test the app's handler with a representative payload:

def test_bounce_webhook_marks_user_undeliverable(client):
    bounce_payload = {
        "event": "bounce",
        "recipient": "bounce@nonexistent.example.com",
        "reason": "550 5.1.1 user unknown",
    }
    response = client.post("/webhooks/email-events", json=bounce_payload)
    assert response.status_code == 200

    user = User.objects.get(email="bounce@nonexistent.example.com")
    assert user.email_status == "undeliverable"

For each ESP, find a sample bounce/complaint payload in the ESP's docs and use it as the test fixture.

Step 8 - DKIM/SPF/DMARC for production-bound emails

These are MTA-side concerns; tests in CI typically don't validate them. For a pre-production layer:

• mail-tester.com: send a test email; receive a 0 - 10 deliverability score covering DKIM/SPF/DMARC + content quality
• dmarcian.com: per-domain DMARC monitoring for production
• Postmark / SendGrid / Mailgun inbound parse sandbox to test what arrives

Step 9 - End-to-end test recipe

For each email flow in scope:

1. ✅ Trigger + capture via Mailpit (Step 2)
2. ✅ Header assertions including List-Unsubscribe (Step 3)
3. ✅ Multipart body - both text + HTML present (Step 4)
4. ✅ Link rewrites resolve to app domain (Step 5)
5. ✅ Unsubscribe one-click POST works (Step 6)
6. ✅ Bounce webhook handler updates user state (Step 7)
7. ✅ Complaint webhook handler updates user state (Step 7)
8. ✅ Pre-prod DKIM/SPF/DMARC verification via mail-tester (out-of-CI; periodic) (Step 8)

Anti-patterns

Limitations

• This is a build-an-X workflow. Tests use the application's HTTP client + an SMTP capture tool (the host SKILL.md or mailhog-legacy.md (opens in new window)).
• DKIM / SPF / DMARC validation requires a real MTA; CI tests cover content + handler logic, not authentication-on-the-wire.
• Per-ESP webhook payloads vary; test fixtures must come from each ESP's official docs.
• Email rendering across clients (Outlook, Gmail, Apple Mail) isn't covered here - that's a pdf-print-render-adjacent domain (visual regression for email).

References

• IETF RFC 2046 §5.1.4 - multipart/alternative
• IETF RFC 8058 - Signaling One-Click Functionality for List-Unsubscribe Email Headers
• IETF RFC 5321 - Simple Mail Transfer Protocol (SMTP)
• IETF RFC 5322 - Internet Message Format
• mail-tester.com - pre-prod deliverability scoring
• dmarcian.com - DMARC monitoring
• The host SKILL.md (Mailpit) + mailhog-legacy.md (opens in new window) - SMTP capture partners
• webhook-delivery-tester - companion: bounce/complaint webhook handlers receive vendor webhooks; same patterns
• sms-test-author, push-notification-test-author - sister channels

Per github.com/mailhog/MailHog (opens in new window):

"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 (the host SKILL.md) succeeded it with richer API + active maintenance. This reference 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 the host SKILL.md (Mailpit).

How to use

1. Install MailHog via Go or Docker and start it - SMTP on 1025, web UI + JSON API on 8025.
2. Point the app under test at localhost:1025 with SMTP auth disabled.
3. In each test, clear the mailbox (DELETE /api/v1/messages), trigger the action that sends mail, then poll APIv2 (/api/v2/messages or /api/v2/search) until the message lands.
4. Assert on the captured message, walking MailHog's nested Content.Headers.Subject array - see the Worked example.
5. Add failure-injection coverage with the Jim chaos monkey (mailhog -invite-jim); when leaving MailHog, follow Migrating to Mailpit.

Install

Per mh-gh (opens in new window):

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

Docker:

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

Default ports

Per mh-gh (opens in new window):

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

Assert via APIv2

Per mh-gh (opens in new window) MailHog has both APIv1 + APIv2; APIv2 is the modern one. Endpoints:

The MailHog message structure is more nested than Mailpit's: Content.Headers.Subject is an array, not the flat Subject field Mailpit exposes. Walk the nested path or the assertion silently fails.

Worked example

Capture and assert a single password-reset email end to end. Clear the mailbox first so a stale message can't satisfy the assertion, trigger the app action, poll APIv2 until the message lands, then assert on its subject and body:

import requests

BASE = "http://localhost:8025"

def test_password_reset_via_mailhog():
    requests.delete(f"{BASE}/api/v1/messages")            # clear (APIv1 - no APIv2 delete)
    trigger_password_reset("alice@example.com")           # app under test sends the email
    msg = poll_for_message(BASE, to="alice@example.com")  # GET /api/v2/search?kind=to&query=...

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

poll_for_message retries GET /api/v2/search?kind=to&query=alice@example.com until a message appears, then returns it. Sub-second SMTP delivery isn't guaranteed, so never assert immediately after triggering.

Jim chaos monkey

Per mh-gh (opens in new window): "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 (host SKILL.md Step 5) - it has richer per-recipient configuration.

CI integration

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

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

Migrating to Mailpit

For new projects, and for teams ready to leave MailHog, migrate to Mailpit (the host SKILL.md) - the actively maintained successor with a flatter API and richer chaos configuration. The feature-mapping table, the schema-rewrite notes, and the step-by-step cutover live in migrating-to-mailpit.md (opens in new window).

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 (opens in new window) - repository
• mailhog/MailHog APIv2 docs - github.com/mailhog/MailHog/blob/master/docs/APIv2.md
• migrating-to-mailpit.md (opens in new window) - feature mapping + cutover steps
• The host SKILL.md (Mailpit) - successor; preferred for new projects
• email-flows.md (opens in new window) - the full email-sending workflow (works with either Mailpit or MailHog)

Deep reference for mailhog-legacy.md (opens in new window). Consult when moving an existing MailHog deployment to Mailpit (the host SKILL.md), the actively maintained successor with a flatter API.

Why migrate

MailHog has had no significant release since ~2020 and is effectively unmaintained. Mailpit is the actively maintained successor with a flatter JSON schema, a single REST API for both reads and deletes, and richer per-recipient chaos configuration.

Feature mapping

Schema rewrite

The largest test-code change is the message schema. MailHog nests the subject as Content.Headers.Subject[0] (an array) and the body as Content.Body; Mailpit exposes a flat Subject string and moves the body to Text. Every assertion that walks MailHog's nested structure must be rewritten against Mailpit's flatter shape.

Cutover steps

1. Stand up Mailpit alongside MailHog on different ports temporarily.
2. Update test code to hit Mailpit's endpoints and flatter schema.
3. Run both in CI in parallel for one PR cycle to confirm parity.
4. Cut over, then retire the MailHog service.

Chaos parity

MailHog's Jim chaos monkey (mailhog -invite-jim) injects random connection drops and slow responses at globally configured probabilities. Mailpit's Chaos mode replaces it with per-recipient configuration, so migrate resilience tests to Mailpit Chaos rather than porting Jim's flags.