Getting started

Install the package.

pip install django-postbox

uv add django-postbox

Add the app.

INSTALLED_APPS = [
    # ...
    "django_postbox",
]

Send your mail through Postbox. Django 6.1 introduced named mailers, older versions use a single backend setting:

MAILERS = {
    "default": {
        "BACKEND": "django_postbox.backends.EmailBackend",
        # Optional: also print every mail in the terminal
        "OPTIONS": {"forward_to": "console"},
    },
    "console": {
        "BACKEND": "django.core.mail.backends.console.EmailBackend",
    },
}

EMAIL_BACKEND = "django_postbox.backends.EmailBackend"

# Optional: also print every mail in the terminal
POSTBOX_FORWARD_BACKEND = "django.core.mail.backends.console.EmailBackend"

Without the forward, mail stops at Postbox and never leaves your machine.

Add the inbox to your URLs, only while developing:

from django.conf import settings
from django.urls import include, path

urlpatterns = [
    # ...
]

if settings.DEBUG:
    urlpatterns += [path("dev/inbox/", include("django_postbox.urls"))]

Create the tables and a staff user. The inbox needs Django’s auth and session tables too, so run all migrations:

python manage.py migrate
python manage.py createsuperuser

Send a mail. Any mail your project sends ends up in Postbox. To try it right away, open a shell:

python manage.py shell

>>> from django.core.mail import send_mail
>>> send_mail("Hello", "Hi Alice", "me@example.com", ["alice@example.com"])
1

Open the inbox.

python manage.py runserver

Go to http://127.0.0.1:8000/dev/inbox/ and log in. Alice’s inbox is waiting for you.