Migration des réglages de messagerie vers le système des envoisLien vers cette rubrique#

Migration des réglagesLien vers cette rubrique#

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 = "user@example.net"
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": "user@example.net",
            "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 readinessLien vers cette rubrique#

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 argumentsLien vers cette rubrique#

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:

  Code

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

  To:

  Code

  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:

  Code

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

  can be updated to:

  Code

  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:

  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:

  Code

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

  And then use it like this:

  Code

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

Replacing fail_silentlyLien vers cette rubrique#

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.

If you use AdminEmailHandler or BrokenLinkEmailsMiddleware and rely on their previous fail-silent behavior, see Ignoring transient failures in error reporting.

Migrating custom email backendsLien vers cette rubrique#

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_passwordLien vers cette rubrique#

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_backendLien vers cette rubrique#

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

Ignoring transient failures in error reportingLien vers cette rubrique#

Django includes two features that report errors via email: AdminEmailHandler and BrokenLinkEmailsMiddleware. In earlier releases, those features used the deprecated fail_silently argument. Starting in Django 2028 – or immediately once the MAILERS setting is defined – those features no longer use fail_silently so no longer ignore certain backend-specific errors.

This may affect projects that use those features with an unreliable SMTP connection and rely on silently ignoring temporary network failures (and certain SMTP configuration errors). If you want to continue dropping error notification emails that cannot be sent, define a MAILERS configuration with the "fail_silently" option enabled for use by those error handlers:

MAILERS = {
    "default": {...},
    "admin-logging": {
        "BACKEND": "django.core.mail.backends.smtp.EmailBackend",
        "OPTIONS": {
            # ... other SMTP options ...
            "fail_silently": True,
        },
    },
}

To use this for AdminEmailHandler, set the "using" option in the LOGGING config as shown in the previous section.

To use this for BrokenLinkEmailsMiddleware, create a subclass that defines using, and then specify the path to that subclass in your MIDDLEWARE setting:

from django.middleware.common import BrokenLinkEmailsMiddleware


class CustomBrokenLinkEmailsMiddleware(BrokenLinkEmailsMiddleware):
    using = "admin-logging"