django-postbox

Catch outgoing Django mail and read it in an inbox per recipient.
For local development, review apps and staging: read password resets, invites and receipts
the way your users will, with HTML, text, headers and attachments. No SMTP server needed.

Documentation · Getting started · Capture and forward · Permissions · Themes · PyPI

Your project sends mail: password resets, invites, order confirmations. While you build them, you want to see them the way your users will, without anything leaving your laptop or test server.

Postbox is a Django email backend that catches every mail and gives each recipient their own inbox. Open /dev/inbox/, click alice@example.com, and read exactly what Alice got: HTML, plain text, headers and attachments.

• An inbox per person. To, Cc and Bcc each get their own copy.
• Live. New mail shows up within five seconds, without reloading.
• Safe. Mail HTML is sandboxed, and only staff can open the inbox by default.
• Fits your setup. Pass mail on to the console or SMTP, and keep it in the database, memory or a cache.
• Four themes, no build step, no CDN.

Works with Python 3.11 to 3.14 and Django 5.2, 6.0 and 6.1.

Quick start

The short version of the Getting started tutorial.

1. Install

pip install django-postbox

2. Add the app and send your mail through Postbox

On Django 6.1+, with named mailers:

# settings.py

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

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",
    },
}

On Django 5.2 and 6.0, replace MAILERS with:

# settings.py

EMAIL_BACKEND = "django_postbox.backends.EmailBackend"

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

3. Add the inbox to your URLs

# urls.py

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

urlpatterns = [
    # ...
]

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

4. Migrate and create a staff user

python manage.py migrate
python manage.py createsuperuser

5. Send a mail

python manage.py shell

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

6. Open the inbox

python manage.py runserver

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

Themes

Pick a default with POSTBOX_THEME, and everyone can choose their own under Options in the inbox. You can also write your own theme in one CSS file.

modern (default)	mail2003
mail2000	mail2010

Documentation

The documentation walks you through everything beyond the quick start:

• Capture and forward: print mail to the terminal, deliver for real and keep a copy, keep your own domain out of the inbox
• Who can read the inbox: staff, a QA group, or everyone while debugging
• Where mail is kept: database, memory or a shared cache
• Themes: the four looks and writing your own
• How it works: how mail is stored and shown safely
• Settings: every setting and when to change it

Development

See Working on Postbox for the full guide.

uv sync
make migrate           # the test project in tests/project
uv run python manage.py createsuperuser
make mail              # send demo mail to ten random people
make rs                # http://127.0.0.1:8000/dev/inbox/

make lint              # ruff, ty and pytest
uv run tox             # every Python and Django version
make docs-serve        # the docs, reloading as you edit
make screenshots       # rebuild docs/img in every theme
make htmx              # update the bundled htmx