Migrating email to mailers¶

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 = "user@example.net"
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": "user@example.net",
            "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". A "host" is required for the SMTP email backend. If your settings didn’t define EMAIL_HOST, set "host" to "localhost" (the default value for the deprecated setting).

• EMAIL_HOST_PASSWORD becomes "password" in "OPTIONS".

• EMAIL_HOST_USER becomes "username" in "OPTIONS". (Note "username" doesn’t quite follow the naming pattern for the other deprecated settings.)

• 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 arguments to get_connection() are still supported, and will simply issue deprecation warnings when MAILERS is defined.)

If a third-party package does either of those, projects that use it will not be able to change to the MAILERS setting until the package has been updated.

Replacing get_connection() and connection arguments¶

The replacements for the deprecated mail.get_connection() function and connection arguments to other mail functions depend on how and why the connections are being created:

• 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 deprecated fail_silently arguments to send_mail(), send_mass_mail(), mail_admins(), mail_managers(), and EmailMessage.send() can be replaced in several ways. Existing usage seems to have several different expectations for the behavior, many of which don’t match the actual (and email backend-dependent) implementation. Consider removing fail_silently entirely if there is not a specific need for it.

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 that sends mail), 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 email backend fail_silently implementation).

• 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 local delivery configurations, SMTP servers may report some recipient errors at send time. If you are using fail_silently specifically to ignore those errors, consider instead intercepting SMTPRecipientsRefused and/or SMTPResponseExceptions with particular smtp_code values as a more precise filter.)

• 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 initializes an 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, or that support older Django versions:

• 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 deprecated auth_user and auth_password arguments to send_mail() and send_mass_mail() can be replaced by defining 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 = {
    # Existing default configuration.
    "default": {
        "OPTIONS": {
            "host": "smtp.example.com",
            "username": "default-user",
            "password": "default-password",
        },
    },
    # Duplicate the default configuration, changing the auth.
    "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 deprecated email_backend argument to the logging AdminEmailHandler can be replaced with a custom MAILERS configuration, referring to it 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",
    },
}