Migrating email to mailers

Django 6.1 introduces the MAILERS setting, replacing EMAIL_BACKEND and several other EMAIL_* settings. It also introduces mail.mailers for obtaining configured email backend instances, replacing mail.get_connection(). A new using argument replaces the earlier connection in Django functions that send email.

The older functionality and settings are still available, but are deprecated and will be removed in Django 7.0. This guide provides details on migrating existing projects to the new mailers functionality.

All Django projects that send email should:

• If using any third-party packages that send email, verify their compatibility with MAILERS before making other changes.

• Update email-related settings.

• Run with deprecation warnings enabled (see Resolving deprecation warnings) to identify other code needing updates.

  Note

  Test suites often use a non-functional email backend, such as the memory backend that Django automatically substitutes during tests. As a result, running tests won’t uncover deprecations that only appear when sending email in production.

  Consider running with deprecation warnings enabled in production to catch those deprecations. Or carefully review your code (including third-party packages) for use of any deprecated email features that will change in Django 7.0.

Other updates are needed only for projects or reusable Django libraries that use these specific features:

• Replacing get_connection() and connection arguments

• Replacing fail_silently

• Migrating custom email backends

• Replacing auth_user and auth_password

• Updating AdminEmailHandler email_backend

Migrating settings

Often, the only change needed to migrate to mailers is updating email-related settings. In your project’s settings, define a MAILERS dict with a "default" entry matching the earlier EMAIL_* settings:

MAILERS = {
    "default": {
        "BACKEND": ...,  # value of EMAIL_BACKEND setting
        "OPTIONS": {
            ...,  # values from other deprecated EMAIL_* settings
        },
    },
}

For example, to update these settings:

EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "mail.example.net"
EMAIL_USE_TLS = True
EMAIL_PORT = 587
EMAIL_HOST_USER = "[e-mail]"
EMAIL_HOST_PASSWORD = "password"

use:

MAILERS = {
    "default": {
        "BACKEND": "django.core.mail.backends.smtp.EmailBackend",
        "OPTIONS": {
            "host": "mail.example.net",
            "use_tls": True,
            # port is not needed: it defaults to 587 with use_tls True.
            "username": "[e-mail]",
            "password": "password",
        },
    },
}

The complete list of deprecated EMAIL_* settings and where they should be moved in a MAILERS configuration is:

• EMAIL_BACKEND becomes "BACKEND". If your settings didn’t define EMAIL_BACKEND, the default value was "django.core.mail.backends.smtp.EmailBackend" (which is also the default if a MAILERS configuration doesn’t specify the "BACKEND").

• EMAIL_FILE_PATH becomes "file_path" in "OPTIONS" (with "BACKEND" set to "django.core.mail.backends.filebased.EmailBackend").

• EMAIL_HOST becomes "host" in "OPTIONS". If your settings didn’t define EMAIL_HOST, the default value was "localhost" and you must add "host": "localhost" to the "OPTIONS" for an SMTP mailer configuration.

• EMAIL_HOST_PASSWORD becomes "password" in "OPTIONS".

• EMAIL_HOST_USER becomes "username" in "OPTIONS".

• EMAIL_PORT becomes "port" in "OPTIONS". It can be omitted if the connection uses the default port for its security (465 for SSL, 587 for TLS, or 25 for an unsecured SMTP connection).

• EMAIL_SSL_CERTFILE becomes "ssl_certfile" in "OPTIONS".

• EMAIL_SSL_KEYFILE becomes "ssl_keyfile" in "OPTIONS".

• EMAIL_TIMEOUT becomes "timeout" in "OPTIONS".

• EMAIL_USE_SSL becomes "use_ssl" in "OPTIONS".

• EMAIL_USE_TLS becomes "use_tls" in "OPTIONS".

For third-party or custom email backends, the available "OPTIONS" depend on the backend. Refer to the third-party documentation, or for custom backends see Migrating custom email backends below.

The Configuring email topic has more information on the MAILERS setting and additional configuration examples.

Reusable library readiness

In most cases, third-party packages that send email through Django will continue working with projects whose settings have been upgraded to use MAILERS. (If they use any deprecated mail features, those will of course cause deprecation warnings.)

There are two deprecated features that are not supported when MAILERS is defined in a project’s settings:

• Trying to access any of the deprecated EMAIL_* settings on django.conf.settings (e.g., checking settings.EMAIL_BACKEND or using settings.EMAIL_HOST_USER).

• Calling mail.get_connection("path.to.EmailBackend") with a specific backend path. (Other uses of get_connection() are still allowed, and will issue deprecation warnings.)

If a third-party package does either of those, projects that use it cannot upgrade to the MAILERS setting until the package has been updated.

Solving “not available when MAILERS is defined” errors

If either of these errors are raised within a third-party package, that indicates it is not compatible with the MAILERS setting:

• AttributeError: "The name setting is not available when MAILERS is defined" where name is EMAIL_BACKEND, EMAIL_HOST, or one of the other deprecated settings.

• RuntimeError: get_connection(backend, ...) is not supported with MAILERS.

If you see these errors, check if a newer version of that dependency is available. If not (and if there are no alternatives to that package), you will need to remove MAILERS from your settings and replace it with the equivalent deprecated email settings until the package has been updated.

Replacing get_connection() and connection arguments

mail.get_connection() is deprecated in Django 6.1, as is the connection argument for passing backend instances directly to mail functions.

The replacement for get_connection() depends on how it is being called:

• get_connection() called with no arguments

  Replace with mailers.default. For example, update this code:

  connection = mail.get_connection()
  connection.send_messages([email1, email2])
  

  To:

  connection = mail.mailers.default
  connection.send_messages([email1, email2])
  

  Note that mailers.default is the default for Django’s mail-sending functions. Code like this:

  mail.send_mail(..., connection=mail.get_connection())
  

  can be updated to:

  mail.send_mail(...)  # No connection arg needed.
  

• get_connection(fail_silently=True)

  See Replacing fail_silently.

• get_connection(...) called with any other arguments

  Define a custom MAILERS configuration with the desired backend and options. Then refer to it in the using argument when sending mail, or obtain an email backend instance from mail.mailers with the configuration name.

  For example, to upgrade this code:

  connection = mail.get_connection(
      "path.to.custom.EmailBackend", option1=True, option2="value"
  )
  mail.send_mail(..., connection=connection)
  connection.send_messages([email1, email2])
  

  Define a custom MAILERS configuration in your settings:

  MAILERS = {
      "default": {...},
      "custom": {
          "BACKEND": "path.to.custom.EmailBackend",
          "OPTIONS": {
              "option1": True,
              "option2": "value",
          },
      },
  }
  

  And then use it like this:

  mail.send_mail(..., using="custom")
  mail.mailers["custom"].send_messages([email1, email2])
  

Replacing fail_silently

The fail_silently arguments to send_mail(), send_mass_mail(), mail_admins(), mail_managers(), and EmailMessage.send() are deprecated.

Handling of fail_silently varies depending on the email backend. A survey of its use suggested that callers have several different expectations for its behavior, many of which don’t match the actual backend implementations.

Calls with fail_silently=True should be updated with one of these options, depending on the caller’s intent:

• To send a message if email has been configured but avoid raising an error if it hasn’t (e.g., in a reusable library), wrap the send call in try: / except mail.MailerDoesNotExist: pass.

• To ignore all exceptions (e.g., to avoid cascading failures in an error handler), wrap the send call in try: / except Exception: pass.

• To ignore only SMTP-related errors, wrap the send call in try / except OSError: pass. Note that this ignores both transient network glitches and SMTP configuration problems (just like the existing SMTP backend fail_silently handling).

• To ignore end user typos in to addresses and other delivery problems, remove the fail_silently argument. Recipient errors are not generally detected at send time, so using fail_silently for this purpose doesn’t accomplish anything and could mask other problems like configuration errors.

  (In certain local delivery configurations, SMTP servers may report some recipient errors at send time. Intercept SMTPRecipientsRefused and/or SMTPResponseExceptions with particular smtp_code values to detect those cases.)

• To create an email configuration that ignores certain backend-dependent errors and reuse it for multiple sending operations, create a custom MAILERS configuration with "fail_silently": True in the "OPTIONS", then refer to that configuration with using in the send call.

Calls with fail_silently=False should be updated to remove the fail_silently arg, as that is the default.

Migrating custom email backends

Custom EmailBackend implementations may need to be updated for compatibility with mailers.

• In the backend’s __init__() method, accept explicit keyword arguments for all configuration options that can come from "OPTIONS". Backends that use custom settings for configuration can continue to do so (or not, as they choose), but keyword arguments should take precedence over settings.

• Accept variable **kwargs and pass them to superclass init. (This will include a new alias argument which must be passed to the superclass.) Ensure that any **kwargs used by the backend are not passed to superclass init, as that would generate an InvalidMailer error for unknown OPTIONS.

• Backends must now handle fail_silently themselves, if they want to support it. There is no requirement to support fail_silently, and backends that don’t offer it should eliminate that keyword argument. (Do not pass an explicit fail_silently arg to superclass init.)

• Do not accept variable positional *args or pass them to superclass init.

The BaseEmailBackend superclass now defines a self.alias attribute. This is useful for error messages (e.g., raise InvalidMailer(f"Bad host {host}", alias=self.alias)), but should not be used for accessing settings.MAILERS directly. All OPTIONS for a mailer configuration are passed to backend init as keyword arguments.

For reusable libraries that want to support compatibility with deprecated mail functions and settings (similar to Django’s built-in email backends):

• A backend can detect it is being initialized without MAILERS by checking if self.alias is None. (Django’s built-in backends check this to decide whether deprecated settings should be used.) Libraries supporting older Django versions will need to use getattr(self, "alias", None).

• Backends that borrow Django’s SMTP email settings like EMAIL_HOST must not try to access them when MAILERS is in use (self.alias is not None), as this will cause a “not available when MAILERS is defined” AttributeError.

• Libraries supporting multiple Django versions can identify support for mailers with either hasattr(django.core.mail, "mailers") or django.VERSION >= (6, 1).

Replacing auth_user and auth_password

The auth_user and auth_password arguments to mail.send_mail() and mail.send_mass_mail() are deprecated. To replace them, define a custom MAILERS configuration with "username" and "password" "OPTIONS", and refer to that configuration with the using argument when sending mail.

For example, to upgrade:

mail.send_mail(..., auth_user="admin", auth_password="admin-password")

Add a custom MAILERS configuration in your settings:

MAILERS = {
    "default": {
        "OPTIONS": {
            "host": "smtp.example.com",
            "username": "default-user",
            "password": "default-password",
        },
    },
    "admin-config": {
        "OPTIONS": {
            "host": "smtp.example.com",
            "username": "admin",
            "password": "admin-password",
        },
    },
}

And then refer to it when sending:

mail.send_mail(..., using="admin-config")

Updating AdminEmailHandler email_backend

The email_backend argument to the logging AdminEmailHandler is deprecated. Replace it with a custom MAILERS configuration and refer to that configuration with the using argument.

For example, if your settings include:

LOGGING = {
    # ...
    "handlers": {
        "mail_admins": {
            "class": "django.utils.log.AdminEmailHandler",
            "email_backend": "third.party.EmailBackend",
        },
    },
    # ...
}

Replace that with:

LOGGING = {
    # ...
    "handlers": {
        "mail_admins": {
            "class": "django.utils.log.AdminEmailHandler",
            "using": "admin-logging",  # defined in MAILERS
        },
    },
    # ...
}

MAILERS = {
    "default": {...},
    "admin-logging": {
        "BACKEND": "third.party.EmailBackend",
    },
}