Django 6.1 introduit le réglage MAILERS, remplaçant EMAIL_BACKEND et plusieurs autres réglages EMAIL_*. Il introduit également mail.mailers pour l’obtention d’instances de moteurs de messagerie configurés, remplaçant mail.get_connection(). Un nouvel argument using remplace l’ancien argument connection dans les fonctions Django qui envoient des courriels.
Ce guide fournit des détails sur la migration de projets existants vers la nouvelle fonctionnalité du système des envois.
\nTous les projets Django qui envoient des courriels devraient :
\nSi des paquets externes sont utilisés pour envoyer des messages, vérifier leur compatibilité avec MAILERS avant de faire d’autres changements.
S’exécuter avec les avertissements d’obsolescence activés (voir Résolution des avertissements d’obsolescence) pour identifier les parties de code nécessitant une mise à jour.
\n\nD’autres mises à jour ne sont nécessaires que pour des projets ou des bibliothèques Django réutilisables qui utilisent ces fonctionnalités spécifiques :
\nSouvent, le seul changement nécessaire pour migrer vers le nouveau style de configuration de messagerie est de mettre à jour les réglages liés à la messagerie. Dans les réglages de votre projet, définissez un dictionnaire MAILERS avec une clé "default" correspondant aux anciens réglages EMAIL_*:
MAILERS = {\n "default": {\n "BACKEND": ..., # value of EMAIL_BACKEND setting\n "OPTIONS": {\n # values from other deprecated EMAIL_* settings\n ...,\n },\n },\n}\nPar exemple, pour mettre à jour ces réglages :
\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"\nutilisez :
\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}\nLa liste complète des réglages EMAIL_* obsolètes et l’endroit vers lequel ils devraient être déplacés dans une configuration MAILERS se trouve ici :
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 devient "password" dans "OPTIONS".
EMAIL_HOST_USER devient "username" dans "OPTIONS" (notez que "username" ne suit pas strictement le schéma de renommage des autres réglages obsolètes).
EMAIL_PORT devient "port" dans "OPTIONS". Il peut être omis si la connexion utilise le port par défaut pour sa sécurité (465 pour SSL, 587 pour TLS, ou 25 pour une connexion SMTP non sécurisée).
EMAIL_SSL_CERTFILE devient "ssl_certfile" dans "OPTIONS".
EMAIL_SSL_KEYFILE devient "ssl_keyfile" dans "OPTIONS".
EMAIL_TIMEOUT devient "timeout" dans "OPTIONS".
EMAIL_USE_SSL devient "use_ssl" dans "OPTIONS".
EMAIL_USE_TLS devient "use_tls" dans "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 argumentsLien vers cette rubrique#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_silentlyLien vers cette rubrique#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.
If you use AdminEmailHandler or BrokenLinkEmailsMiddleware\nand rely on their previous fail-silent behavior, see\nIgnoring transient failures in error reporting.
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_passwordLien vers cette rubrique#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_backendLien vers cette rubrique#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}\nDjango includes two features that report errors via email:\nAdminEmailHandler and BrokenLinkEmailsMiddleware. In\nearlier releases, those features used the deprecated fail_silently argument. Starting in Django 2028 – or\nimmediately once the MAILERS setting is defined – those features no\nlonger use fail_silently so no longer ignore certain backend-specific\nerrors.
This may affect projects that use those features with an unreliable SMTP\nconnection and rely on silently ignoring temporary network failures (and\ncertain SMTP configuration errors). If you want to continue dropping error\nnotification emails that cannot be sent, define a MAILERS\nconfiguration with the "fail_silently" option enabled for use by those\nerror handlers:
MAILERS = {\n "default": {...},\n "admin-logging": {\n "BACKEND": "django.core.mail.backends.smtp.EmailBackend",\n "OPTIONS": {\n # ... other SMTP options ...\n "fail_silently": True,\n },\n },\n}\nTo use this for AdminEmailHandler, set the "using" option in the\nLOGGING config as shown in the previous section.
To use this for BrokenLinkEmailsMiddleware, create a subclass that\ndefines using, and then specify the path to that subclass in your\nMIDDLEWARE setting:
from django.middleware.common import BrokenLinkEmailsMiddleware\n\n\nclass CustomBrokenLinkEmailsMiddleware(BrokenLinkEmailsMiddleware):\n using = "admin-logging"\n