django-error-mail-dedup

Deduplicate identical Django admin error emails in short bursts (like frontend retry storms) so operators receive signal, not spam.

Features

• Drop-in replacement for Django's AdminEmailHandler
• Suppresses duplicates of the same underlying error within a configurable time window, even when they come from different requests/users (dedup is keyed on exception type + message + originating source line, not on the full email body, so per-request details like client IP or query params don't defeat it)
• Sends summary emails for suppressed duplicates
• Works across multiple workers when they share a state file path
• Falls back to in-process dedup state if shared file state is unavailable (a warning is logged when this happens)
• Never lets a handler failure break the request that triggered it (errors during dedup/email-building are routed through the standard logging.Handler.handleError, matching Django's own AdminEmailHandler behavior)

Install

pip install django-error-mail-dedup

Quick start

In Django LOGGING settings:

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "filters": {
        "require_debug_false": {"()": "django.utils.log.RequireDebugFalse"},
    },
    "handlers": {
        "mail_admins": {
            "level": "ERROR",
            "filters": ["require_debug_false"],
            "class": "django_error_mail_dedup.handlers.DedupAdminEmailHandler",
            "dedup_window_seconds": 180,
            "summary_email_every_seconds": 60,
            "state_file_path": "/var/log/myapp/error_email_dedup_state.json",
        }
    },
    "loggers": {
        "django.request": {
            "handlers": ["mail_admins"],
            "level": "ERROR",
            "propagate": True,
        }
    },
}

Configuration

• dedup_window_seconds (int, default 180)
  • Identical error emails during this window are suppressed.
• summary_email_every_seconds (int, default 60)
  • If duplicates keep coming, send periodic summary emails.
• state_file_path (str | None, default None)
  • When set, dedup state is shared between worker processes via file lock.
  • Use a location writable by all app workers.
  • If omitted, dedup works per-process only.

Notes for multi-worker deployments

• Single host / shared filesystem: use state_file_path for cross-worker dedup.
• Multiple pods/hosts without shared filesystem: dedup is per-instance. A cache backend (Redis etc.) can be added in future versions.

Development

pip install -e .[dev]
pytest -q