Integration Guide

SMTP testing with Django

Configure Django's email backend to capture and inspect every email through MailHog.

Why test Django emails with MailHog?

Django's built-in django.core.mail makes sending emails easy, but testing them is another story. The default console.EmailBackend dumps emails to stdout — you can't inspect HTML, check spam scores, or verify rendering across clients. MailHog gives you a real SMTP server that captures everything.

Quickstart: Django settings

Add these settings to your settings.py (or settings/dev.py):

# settings/dev.py
import os

EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = os.environ.get("SMTP_HOST", "smtp.mailhog.site")
EMAIL_PORT = int(os.environ.get("SMTP_PORT", "2525"))
EMAIL_HOST_USER = os.environ.get("SMTP_USER", "")
EMAIL_HOST_PASSWORD = os.environ.get("SMTP_PASS", "")
EMAIL_USE_TLS = False

Send a test email

from django.core.mail import send_mail

send_mail(
    subject="Welcome to our platform",
    message="Thanks for signing up!",
    from_email="noreply@yourapp.com",
    recipient_list=["user@example.com"],
    html_message="<h1>Welcome!</h1><p>Thanks for signing up.</p>",
)
# Check your MailHog dashboard — email appears instantly ✅

Testing with pytest

import requests

def test_password_reset_email(client, mailhog_api):
    # Trigger password reset
    client.post("/api/forgot-password/", {"email": "user@test.com"})

    # Query MailHog API for captured email
    res = requests.get(
        f"{MAILHOG_URL}/api/v1/inbox/{INBOX_ID}/messages",
        headers={"X-API-Key": API_KEY},
        params={"to": "user@test.com"},
    )
    emails = res.json()["data"]

    assert len(emails) >= 1
    assert "Reset your password" in emails[0]["subject"]
    assert "user@test.com" in emails[0]["to"][0]["address"]

Common pitfalls

Using EMAIL_USE_TLS = True with port 2525 — this will fail
Forgetting to switch EMAIL_BACKEND from console to smtp in dev settings
Not using html_message parameter — most Django emails are plain-text only by default
Running tests with Django's in-memory email backend instead of MailHog

Start testing Django emails

Get SMTP credentials in 60 seconds.

Start free →