django/django · error · NotImplementedError

subclasses of BaseEmailBackend must override send_messages()

Error message

subclasses of BaseEmailBackend must override send_messages() method

What it means

Raised as a NotImplementedError by BaseEmailBackend.send_messages() because send_messages is the abstract contract of an email backend: it must be overridden by every concrete subclass to actually deliver EmailMessage objects. Calling it on the base class (or a subclass that forgot to override it) yields this error.

Source

Thrown at django/core/mail/backends/base.py:124

        pass

    def __enter__(self):
        try:
            self.open()
        except Exception:
            self.close()
            raise
        return self

    def __exit__(self, exc_type, exc_value, traceback):
        self.close()

    def send_messages(self, email_messages):
        """
        Send one or more EmailMessage objects and return the number of email
        messages sent.
        """
        raise NotImplementedError(
            "subclasses of BaseEmailBackend must override send_messages() method"
        )

View on GitHub (pinned to ae25a40be0)

Solutions

1. Override send_messages(self, email_messages) in your backend subclass, returning the number of messages sent.
2. If you didn't intend to write a backend, use a built-in backend (smtp, console, file, locmem, dummy) via EMAIL_BACKEND or MAILERS.
3. Ensure any abstract/mixin backend base is subclassed before use.

Example fix

// before
class MyBackend(BaseEmailBackend):
    pass  // forgot send_messages
// after
class MyBackend(BaseEmailBackend):
    def send_messages(self, email_messages):
        sent = 0
        for msg in email_messages:
            self._deliver(msg); sent += 1
        return sent

from django.core.mail.backends.base import BaseEmailBackend
def assert_overrides_send_messages(backend_cls):
    if backend_cls.send_messages is BaseEmailBackend.send_messages:
        raise NotImplementedError('subclass must override send_messages')
    return backend_cls

from django.core.mail.backends.base import BaseEmailBackend
def backend_implements_send_messages(backend_cls) -> bool:
    return backend_cls.send_messages is not BaseEmailBackend.send_messages

When it happens

Trigger: Instantiating BaseEmailBackend directly and calling send_messages; a custom backend subclass whose author forgot to define send_messages; a backend class meant only as a mixin that was used directly.

Common situations: Writing a custom email backend and missing the send_messages implementation; instantiating the wrong (base) class; testing scaffolding that uses the base class.

Related errors

• Distance operations not available on this spatial backend.
• Aggregate support not implemented for this spatial backend.
• {type(self).__name__!r} object has no attribute {name!r}
• Deprecated email settings are not allowed when MAILERS is de
• The {name} setting is not available when MAILERS is defined.

AI-assisted analysis of django/django@ae25a40be0 (2026-08-06). Data as JSON: /api/errors/75e1fe74e493510d. Report an issue: GitHub.