Test Django emails locally on your Mac

Catch every email your Django app sends with a local SMTP server on your Mac. One settings block, one test command, and you can inspect each email instantly.

Django’s console backend prints emails to your terminal, which works until you need to see the HTML version or check an attachment. With Mailbox, Django sends real SMTP to a server on your Mac and every email appears fully rendered — HTML, plain text, headers and attachments. Nothing is delivered to real recipients.

1. Start a server in Mailbox

Open Mailbox. On first launch it creates a server on port 2525 — make sure it’s started. If you add another server instead, Mailbox picks a free port for it; use that port in the steps below.

2. Update your settings

Django 6.1 replaced the EMAIL_* settings with a single MAILERS setting, and new projects already define it with the console backend. Edit that block in your development settings:

MAILERS = {
    "default": {
        "BACKEND": "django.core.mail.backends.smtp.EmailBackend",
        "OPTIONS": {"host": "127.0.0.1", "port": 2525},
    },
}

Set the port explicitly — without TLS, Django defaults to port 25. Don’t add EMAIL_* settings next to MAILERS; Django refuses to start when both are defined.

Django 6.0 and older

Projects without MAILERS use the classic settings (on 6.1 they still work, with a deprecation warning):

EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "127.0.0.1"
EMAIL_PORT = 2525
EMAIL_USE_TLS = False
EMAIL_USE_SSL = False

Either way, don’t set a user name or password: Mailbox doesn’t support SMTP authentication, and Django fails with SMTPNotSupportedError if it tries to log in.

3. Send a test email

Django ships a management command for exactly this:

python manage.py sendtestemail test@example.com

Or from python manage.py shell:

from django.core.mail import send_mail

send_mail("Hello from Django", "It works!", None, ["test@example.com"])

Both show up in Mailbox immediately. Password reset emails, mail_admins error reports and your own EmailMultiAlternatives go the same way.

Running Django in Docker

Inside a container, 127.0.0.1 refers to the container. Use your Mac’s address instead — "host": "host.docker.internal" in MAILERS, or:

EMAIL_HOST = "host.docker.internal"

If the container still can’t connect, turn on Allow Network Access in Mailbox (Settings → General) and restart the server, so it accepts connections from outside the loopback interface.

Troubleshooting

  • ConnectionRefusedError — the Mailbox server isn’t running, or EMAIL_PORT doesn’t match.
  • ImproperlyConfigured: Deprecated email settings are not allowed when MAILERS is defined — remove the EMAIL_* settings and configure MAILERS only.
  • Emails still printed to the terminal — another settings module still uses the console backend; check which module DJANGO_SETTINGS_MODULE points to.
  • Celery tasks don’t send — emails sent from tasks need a running worker.

What to check next

With real emails in front of you, run the HTML compatibility check to find CSS that email clients like Outlook won’t render, and use the mobile preview to check responsive templates. If you test several projects, Mailbox Pro lets you give each its own server and port so their emails stay separate.

More guides