Migration des réglages de messagerie vers le système des envois

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.

Tous les projets Django qui envoient des courriels devraient :

• Si des paquets externes sont utilisés pour envoyer des messages, vérifier leur compatibilité avec MAILERS avant de faire d’autres changements.

• Mettre à jour les réglages liés à la messagerie.

• 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.

  Note

  Le lancement des tests ne révèle pas toujours tous les endroits à mettre à jour. Les suites de test utilisent fréquemment un moteur de messagerie non fonctionnel (tel que le moteur basé en mémoire que Django utilise durant les tests), et peuvent donc manquer des avertissements d’obsolescence qui ne sont déclenchés qu’avec une configuration de messagerie en 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.

D’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 :

• Replacing get_connection() and connection arguments

• Replacing fail_silently

• Migrating custom email backends

• Replacing auth_user and auth_password

• Updating AdminEmailHandler email_backend

Obsolète depuis la version 6.1: Les réglages et fonctions suivantes seront supprimées dans Django 2028 :

• EMAIL_BACKEND, EMAIL_FILE_PATH, EMAIL_HOST, EMAIL_HOST_PASSWORD, EMAIL_HOST_USER, EMAIL_PORT, EMAIL_SSL_CERTFILE, EMAIL_SSL_KEYFILE, EMAIL_TIMEOUT, EMAIL_USE_SSL, EMAIL_USE_TLS

• mail.get_connection() et les arguements connection des fonctions d’envoi de messages

• L’argument fail_silently de send_mail(), send_mass_mail(), mail_admins(), mail_managers() et EmailMessage.send()

• Les arguments auth_user et auth_password de send_mail() et send_mass_mail()

• L’argument email_backend de AdminEmailHandler

Migration des réglages

Souvent, 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 = {
    "default": {
        "BACKEND": ...,  # value of EMAIL_BACKEND setting
        "OPTIONS": {
            # values from other deprecated EMAIL_* settings
            ...,
        },
    },
}

Par exemple, pour mettre à jour ces réglages :

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"

utilisez :

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",
        },
    },
}

La 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 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 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 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.

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.

If those errors are coming from your own code, see the other sections in this migration guide for recommended updates.

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",
    },
}