stapel-mailtrap

An email trap (mail catcher) for dev/staging: outbound mail is captured into a TrappedEmail journal instead of being sent, and browsed through a read-only "Mail" API. Plugs into stapel-notifications' email-provider seam by dotted path — no module-to-module import.

Part of the Stapel framework — composable Django apps that deploy as a monolith or as microservices without changing module code.

Install

pip install stapel-mailtrap

# settings.py
INSTALLED_APPS = [
    # ...
    "stapel_mailtrap",
]

# urls.py
path("mailtrap/", include("stapel_mailtrap.urls"))

python manage.py migrate

Trapping notifications email

Point stapel-notifications' email provider at the trap — one setting, no code:

STAPEL_NOTIFICATIONS = {
    "EMAIL_PROVIDER": "stapel_mailtrap.provider.MailtrapEmailProvider",
}

Every email stapel-notifications would send is now persisted and inspectable instead. The provider matches the notifications email duck type (send(recipient, subject, html_body, headers)) — see MODULE.md §3.

Trapping any backend

For a host whose own mail path should trap, call the service directly:

from stapel_mailtrap import trap_email

trap_email(
    to_email="alice@example.com",
    from_email="bot@example.com",
    subject="Your code",
    body_html="<b>123456</b>",
    body_text="123456",
    attachments=[{"filename": "invoice.pdf", "content_type": "application/pdf", "size": 8123}],
    scope_key="workspace-42",   # opaque host scope
)

It persists the row and emits mailtrap.email.trapped transactionally. Attachments are metadata only — raw bytes are never stored.

HTTP API ("Письма" / Mail)

Read-only (the trap is filled by the provider / trap_email, never via the API):

Default permission is staff/service only (trapped mail can contain OTPs and magic links). Override permission_classes and set a SCOPE_PROVIDER for per-tenant visibility — see MODULE.md.

Retention

STAPEL_MAILTRAP = {
    "MAX_EMAILS": 1000,   # hard cap on stored rows (0 disables)
    "TTL_DAYS": 30,       # delete rows older than N days (0 disables)
}

Run the sweep from any scheduler:

python manage.py purge_trapped_emails            # --dry-run supported

Or schedule the Celery task (celery is an optional host dependency):

CELERY_BEAT_SCHEDULE = {
    "purge-trapped-emails": {
        "task": "stapel_mailtrap.tasks.purge_trapped_emails",
        "schedule": crontab(hour=3, minute=0),   # nightly
    },
}

Settings

All configuration lives in the STAPEL_MAILTRAP namespace (dict setting, flat setting, or env var — resolved lazily):

comm surface

Extension points

See MODULE.md — the agent-facing map of every fork-free seam (settings, the ScopeProvider seam, the notifications email-provider adapter with its duck-typed contract, serializer seams, permissions, comm surface, system checks).

Development

pip install -e . && pip install pytest pytest-django pytest-cov ruff jsonschema
./setup-hooks.sh
pytest tests/

License

MIT