Skip to content

[pull] main from django:main #435

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pull merged 1 commit into from
May 29, 2026
+55 −42
Merged

[pull] main from django:main #435

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 42 additions & 35 deletions docs/howto/mailers-migration.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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" <MAILERS-OPTIONS>`, and
refer to that configuration with the ``using`` argument when sending mail.

Expand Down Expand Up @@ -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::

Expand Down
20 changes: 13 additions & 7 deletions docs/ref/settings.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 = {
Expand All @@ -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

Expand Down
Loading