Django 6.1 introduced the MAILERS setting, replacing\nEMAIL_BACKEND and several other EMAIL_* settings. It also\nintroduced mail.mailers for obtaining configured email backend\ninstances, replacing mail.get_connection(). A new using argument\nreplaces the earlier connection in Django functions that send email.
This guide provides details on migrating existing projects to the new mailers\nfunctionality.
\nAll Django projects that send email should:
\nIf using any third-party packages that send email, verify their\ncompatibility with MAILERS\nbefore making other changes.
Run with deprecation warnings enabled (see\n处理过期警告) to identify\nother code needing updates.
\n\nOther updates are needed only for projects or reusable Django libraries that\nuse these specific features:
\nOften, the only change needed to migrate to mailers is updating email-related\nsettings. In your project's settings, define a MAILERS dict with a\n"default" entry matching the earlier EMAIL_* settings:
MAILERS = {\n "default": {\n "BACKEND": ..., # value of EMAIL_BACKEND setting\n "OPTIONS": {\n # values from other deprecated EMAIL_* settings\n ...,\n },\n },\n}\nFor example, to update these settings:
\nEMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"\nEMAIL_HOST = "mail.example.net"\nEMAIL_USE_TLS = True\nEMAIL_PORT = 587\nEMAIL_HOST_USER = "user@example.net"\nEMAIL_HOST_PASSWORD = "password"\nuse:
\nMAILERS = {\n "default": {\n "BACKEND": "django.core.mail.backends.smtp.EmailBackend",\n "OPTIONS": {\n "host": "mail.example.net",\n "use_tls": True,\n # port is not needed: it defaults to 587 with use_tls True.\n "username": "user@example.net",\n "password": "password",\n },\n },\n}\nThe complete list of deprecated EMAIL_* settings and where they should be\nmoved in a MAILERS configuration is:
EMAIL_BACKEND becomes "BACKEND". If your settings didn't\ndefine EMAIL_BACKEND, the default value was\n"django.core.mail.backends.smtp.EmailBackend" (which is also the default\nif a MAILERS configuration doesn't specify the "BACKEND").
EMAIL_FILE_PATH becomes "file_path" in "OPTIONS" (with\n"BACKEND" set to "django.core.mail.backends.filebased.EmailBackend").
EMAIL_HOST becomes "host" in "OPTIONS". A "host" is\nrequired for the SMTP email backend. If your settings didn't define\nEMAIL_HOST, set "host" to "localhost" (the default value for the\ndeprecated setting).
EMAIL_HOST_PASSWORD becomes "password" in "OPTIONS".
EMAIL_HOST_USER becomes "username" in "OPTIONS". (Note\n"username" doesn't quite follow the naming pattern for the other\ndeprecated settings.)
EMAIL_PORT becomes "port" in "OPTIONS". It can be omitted\nif the connection uses the default port for its security (465 for SSL, 587\nfor 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\nthe backend. Refer to the third-party documentation, or for custom backends see\nMigrating custom email backends below.
The Configuring email topic has more information on the\nMAILERS setting and additional configuration examples.
In most cases, third-party packages that send email through Django will\ncontinue working with projects whose settings have been upgraded to use\nMAILERS. (If they use any deprecated mail features, those will of\ncourse cause deprecation warnings.)
There are two deprecated features that are not supported when\nMAILERS is defined in a project's settings:
Trying to access any of the deprecated EMAIL_* settings on\ndjango.conf.settings (e.g., checking settings.EMAIL_BACKEND or using\nsettings.EMAIL_HOST_USER).
Calling mail.get_connection("path.to.EmailBackend") with a specific backend path. (Other arguments to\nget_connection() are still supported, and will simply issue deprecation\nwarnings when MAILERS is defined.)
If a third-party package does either of those, projects that use it will not be\nable to change to the MAILERS setting until the package has been\nupdated.
If either of these errors are raised within a third-party package, that\nindicates it is not compatible with the MAILERS setting:
AttributeError: "The name setting is not available when MAILERS is\ndefined" where name is EMAIL_BACKEND, EMAIL_HOST,\nor 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\navailable. If not (and if there are no alternatives to that package), you will\nneed to remove MAILERS from your settings and replace it with the\nequivalent deprecated email settings until\nthe package has been updated.
If those errors are coming from your own code, see the other sections in this\nmigration guide for recommended updates.
\nget_connection() and connection argumentsLink to this heading#The replacements for the deprecated mail.get_connection() function\nand connection arguments to other mail functions depend on how and why\nthe connections are being created:
get_connection() called with no arguments
Replace with mailers.default. For example, update this code:
connection = mail.get_connection()\nconnection.send_messages([email1, email2])\nTo:
\nconnection = mail.mailers.default\nconnection.send_messages([email1, email2])\nNote that mailers.default is the default for Django's mail-sending\nfunctions. Code like this:
mail.send_mail(..., connection=mail.get_connection())\ncan be updated to:
\nmail.send_mail(...) # No connection arg needed.\nget_connection(fail_silently=True)
get_connection(...) called with any other arguments
Define a custom MAILERS configuration with the desired backend\nand options. Then refer to it in the using argument when sending mail,\nor obtain an email backend instance from mail.mailers with the\nconfiguration name.
For example, to upgrade this code:
\nconnection = mail.get_connection(\n "path.to.custom.EmailBackend", option1=True, option2="value"\n)\nmail.send_mail(..., connection=connection)\nconnection.send_messages([email1, email2])\nDefine a custom MAILERS configuration in your settings:
MAILERS = {\n "default": {...},\n "custom": {\n "BACKEND": "path.to.custom.EmailBackend",\n "OPTIONS": {\n "option1": True,\n "option2": "value",\n },\n },\n}\nAnd then use it like this:
\nmail.send_mail(..., using="custom")\nmail.mailers["custom"].send_messages([email1, email2])\nfail_silentlyLink to this heading#The deprecated fail_silently arguments to send_mail(),\nsend_mass_mail(), mail_admins(), mail_managers(), and\nEmailMessage.send() can be replaced in several ways. Existing usage\nseems to have several different expectations for the behavior, many of which\ndon't match the actual (and email backend-dependent) implementation. Consider\nremoving 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,\ndepending on the caller's intent:
To send a message if email has been configured but avoid raising an error\nif it hasn't (e.g., in a reusable library), wrap the send call in try: /\nexcept mail.MailerDoesNotExist: pass.
To ignore all exceptions (e.g., to avoid cascading failures in an error\nhandler that sends mail), wrap the send call in try: / except\nException: pass.
To ignore only SMTP-related errors, wrap the send call in try /\nexcept OSError: pass. Note that this ignores both transient network\nglitches and SMTP configuration problems (just like the existing SMTP\nemail backend fail_silently implementation).
To ignore end user typos in to addresses and other delivery problems,\nremove the fail_silently argument. Recipient errors are not generally\ndetected at send time, so using fail_silently for this purpose doesn't\naccomplish anything and could mask other problems like configuration errors.
(In local delivery configurations, SMTP servers may report some recipient\nerrors at send time. If you are using fail_silently specifically to\nignore those errors, consider instead intercepting\nSMTPRecipientsRefused and/or\nSMTPResponseExceptions with particular smtp_code\nvalues as a more precise filter.)
To create an email configuration that ignores certain backend-dependent\nerrors and reuse it for multiple sending operations, create a custom\nMAILERS configuration with "fail_silently": True in the\n"OPTIONS", then refer to that configuration\nwith using in the send call.
Calls with fail_silently=False should be updated to remove the\nfail_silently arg, as that is the default.
Custom EmailBackend implementations may need to be updated for\ncompatibility with mailers.
In the backend's __init__() method, accept explicit keyword arguments for\nall configuration options that can come from "OPTIONS". Backends that use custom settings for configuration can\ncontinue to do so (or not, as they choose), but keyword arguments should take\nprecedence over settings.
Accept variable **kwargs and pass them to superclass init. (This will\ninclude a new alias argument which must be passed to the superclass.)\nEnsure that any **kwargs used by the backend are not passed to\nsuperclass init, as that would generate an InvalidMailer error for\nunknown OPTIONS.
Backends must now handle fail_silently themselves, if they want to\nsupport it. There is no requirement to support fail_silently, and\nbackends that don't offer it should eliminate that keyword argument. (Do not\npass 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.\nThis is useful for error messages (e.g., raise InvalidMailer(f"Bad host\n{host}", alias=self.alias)), but should not be used for accessing\nsettings.MAILERS directly. All OPTIONS for a mailer configuration are\npassed to backend init as keyword arguments.
For reusable libraries that want to support compatibility with deprecated mail\nfunctions and settings, or that support older Django versions:
\nA backend can detect it is being initialized without MAILERS by\nchecking if self.alias is None. (Django's built-in backends check this to\ndecide whether deprecated settings should be used.) Libraries supporting\nolder Django versions will need to use getattr(self, "alias", None).
Backends that borrow Django's SMTP email settings like EMAIL_HOST\nmust not try to access them when MAILERS is in use (self.alias\nis not None), as this will cause a "not available when MAILERS is defined"\nAttributeError.
Libraries supporting multiple Django versions can identify support for\nmailers with either hasattr(django.core.mail, "mailers") or\ndjango.VERSION >= (6, 1).
auth_user and auth_passwordLink to this heading#The deprecated auth_user and auth_password arguments to\nsend_mail() and send_mass_mail() can be replaced by defining a\ncustom MAILERS configuration with\n"username" and "password" "OPTIONS", and\nrefer to that configuration with the using argument when sending mail.
For example, to upgrade:
\nmail.send_mail(..., auth_user="admin", auth_password="admin-password")\nAdd a custom MAILERS configuration in your settings:
MAILERS = {\n # Existing default configuration.\n "default": {\n "OPTIONS": {\n "host": "smtp.example.com",\n "username": "default-user",\n "password": "default-password",\n },\n },\n # Duplicate the default configuration, changing the auth.\n "admin-config": {\n "OPTIONS": {\n "host": "smtp.example.com",\n "username": "admin",\n "password": "admin-password",\n },\n },\n}\nAnd then refer to it when sending:
\nmail.send_mail(..., using="admin-config")\nemail_backendLink to this heading#The deprecated email_backend argument to the logging\nAdminEmailHandler can be replaced with a custom\nMAILERS configuration, referring to it with the using\nargument.
For example, if your settings include:
\nLOGGING = {\n # ...\n "handlers": {\n "mail_admins": {\n "class": "django.utils.log.AdminEmailHandler",\n "email_backend": "third.party.EmailBackend",\n },\n },\n # ...\n}\nReplace that with:
\nLOGGING = {\n # ...\n "handlers": {\n "mail_admins": {\n "class": "django.utils.log.AdminEmailHandler",\n "using": "admin-logging", # defined in MAILERS\n },\n },\n # ...\n}\n\nMAILERS = {\n "default": {...},\n "admin-logging": {\n "BACKEND": "third.party.EmailBackend",\n },\n}\n