From 7711cceea646340e07fcee4cef8245f201b98211 Mon Sep 17 00:00:00 2001 From: Natalia <124304+nessita@users.noreply.github.com> Date: Thu, 28 May 2026 13:50:28 -0300 Subject: [PATCH] Refs #35514 -- Improved docs for MAILERS setting and mailers migration guide. Thanks Mike Edmunds for flagging these issues and for the review. --- docs/howto/mailers-migration.txt | 77 +++++++++++++++++--------------- docs/ref/settings.txt | 20 ++++++--- 2 files changed, 55 insertions(+), 42 deletions(-) diff --git a/docs/howto/mailers-migration.txt b/docs/howto/mailers-migration.txt index 65aecdfc86f4..c99d0de5cce2 100644 --- a/docs/howto/mailers-migration.txt +++ b/docs/howto/mailers-migration.txt @@ -1,10 +1,12 @@ +.. RemovedInDjango70Warning: Remove this file and references to it. + .. _migrating-to-mailers: ========================== Migrating email to mailers ========================== -Django has introduced the :setting:`MAILERS` setting, replacing +Django 6.1 introduced the :setting:`MAILERS` setting, replacing :setting:`EMAIL_BACKEND` and several other ``EMAIL_*`` settings. It also introduced :data:`.mail.mailers` for obtaining configured email backend instances, replacing :func:`.mail.get_connection`. A new ``using`` argument @@ -46,6 +48,29 @@ use these specific features: * :ref:`migrating-to-mailers-auth` * :ref:`migrating-to-mailers-adminemailhandler` +.. deprecated:: 6.1 + + The following settings and functions will be removed in Django 7.0: + + * :setting:`EMAIL_BACKEND`, :setting:`EMAIL_FILE_PATH`, + :setting:`EMAIL_HOST`, :setting:`EMAIL_HOST_PASSWORD`, + :setting:`EMAIL_HOST_USER`, :setting:`EMAIL_PORT`, + :setting:`EMAIL_SSL_CERTFILE`, :setting:`EMAIL_SSL_KEYFILE`, + :setting:`EMAIL_TIMEOUT`, :setting:`EMAIL_USE_SSL`, + :setting:`EMAIL_USE_TLS` + + * :func:`.mail.get_connection` and the ``connection`` arguments to mail + functions + + * The ``fail_silently`` argument to :func:`.send_mail`, + :func:`.send_mass_mail`, :func:`.mail_admins`, :func:`.mail_managers`, + and :meth:`.EmailMessage.send` + + * The ``auth_user`` and ``auth_password`` arguments to :func:`.send_mail` + and :func:`.send_mass_mail` + + * The ``email_backend`` argument to :class:`.AdminEmailHandler` + .. _migrating-to-mailers-settings: Migrating settings @@ -93,11 +118,6 @@ use:: .. _deprecated-email-settings: -.. deprecated:: 6.1 - - The :setting:`EMAIL_BACKEND` and related ``EMAIL_*`` settings are - deprecated. - The complete list of deprecated ``EMAIL_*`` settings and where they should be moved in a :setting:`MAILERS` configuration is: @@ -181,12 +201,9 @@ migration guide for recommended updates. Replacing ``get_connection()`` and ``connection`` arguments ----------------------------------------------------------- -.. deprecated:: 6.1 - - :func:`.mail.get_connection` and the ``connection`` argument for passing - backend instances directly to mail functions are deprecated. - -The replacement for ``get_connection()`` depends on how it is being called: +The replacements for the deprecated :func:`.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 @@ -251,16 +268,12 @@ The replacement for ``get_connection()`` depends on how it is being called: Replacing ``fail_silently`` --------------------------- -.. deprecated:: 6.1 - - The ``fail_silently`` argument to :func:`.send_mail`, - :func:`.send_mass_mail`, :func:`.mail_admins`, :func:`.mail_managers`, and - :meth:`.EmailMessage.send` are deprecated. - -Existing code using ``fail_silently`` seems to have several different -expectations for its 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. +The deprecated ``fail_silently`` arguments to :func:`.send_mail`, +:func:`.send_mass_mail`, :func:`.mail_admins`, :func:`.mail_managers`, and +:meth:`.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: @@ -354,12 +367,9 @@ functions and settings, or that support older Django versions: Replacing ``auth_user`` and ``auth_password`` --------------------------------------------- -.. deprecated:: 6.1 - - The ``auth_user`` and ``auth_password`` arguments to :func:`.send_mail` - and :func:`.send_mass_mail` are deprecated. - -To replace them, define a custom :setting:`MAILERS` configuration with +The deprecated ``auth_user`` and ``auth_password`` arguments to +:func:`.send_mail` and :func:`.send_mass_mail` can be replaced by defining a +custom :setting:`MAILERS` configuration with ``"username"`` and ``"password"`` :setting:`"OPTIONS" `, and refer to that configuration with the ``using`` argument when sending mail. @@ -397,13 +407,10 @@ And then refer to it when sending:: Updating AdminEmailHandler ``email_backend`` -------------------------------------------- -.. deprecated:: 6.1 - - The ``email_backend`` argument to the logging :class:`.AdminEmailHandler` - is deprecated. - -Replace it with a custom :setting:`MAILERS` configuration and refer to that -configuration with the ``using`` argument. +The deprecated ``email_backend`` argument to the logging +:class:`.AdminEmailHandler` can be replaced with a custom +:setting:`MAILERS` configuration, referring to it with the ``using`` +argument. For example, if your settings include:: diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 38e27d2dc17a..4cd1fa7368d2 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -2158,11 +2158,14 @@ configuration process will be skipped. .. versionadded:: 6.1 -Default: no default until the deprecation ends, then ``{}``. +.. RemovedInDjango70Warning: Update the default value to be ``{}``. + +Default: Not defined A dictionary containing the settings for all email backends to be used with Django. It is a nested dictionary that maps backend aliases to dictionaries containing each mailer's backend import path and configuration options. + Example:: MAILERS = { @@ -2187,16 +2190,19 @@ If you plan to send email through Django, configuring at least a ``"default"`` mailer is recommended. Any number of additional mailers may also be specified. Depending on which backend is used, other options may be required. +Setting ``MAILERS`` to an empty dictionary (``{}``) disables email sending and +any attempt to send mail will raise ``MailerDoesNotExist``. + See :ref:`topic-email-configuration` for more information. .. deprecated:: 6.1 - In Django 7.0, the default value will change to ``{}`` (no defined email - mailers). Until then, if ``MAILERS`` is not defined in the - settings, Django will create a ``"default"`` mailer from the - deprecated :setting:`EMAIL_BACKEND` setting. Projects can opt into the - Django 7.0 behavior early by adding ``MAILERS`` and removing - ``EMAIL_BACKEND`` from their settings. + In Django 7.0, the default value will change from "Not defined" to ``{}``. + Until then, if ``MAILERS`` is not defined in the project's settings, Django + will create a ``"default"`` mailer using the :setting:`EMAIL_BACKEND` + setting. Projects can opt into the Django 7.0 behavior at any time by + adding ``MAILERS`` and removing ``EMAIL_BACKEND`` from their settings. See + :ref:`migrating-to-mailers-settings`. .. setting:: MAILERS-BACKEND