44Migrating email to mailers
55==========================
66
7- Django 6.1 introduces the :setting:`MAILERS` setting, replacing
7+ Django has introduced the :setting:`MAILERS` setting, replacing
88:setting:`EMAIL_BACKEND` and several other ``EMAIL_*`` settings. It also
9- introduces :data:`.mail.mailers` for obtaining configured email backend
9+ introduced :data:`.mail.mailers` for obtaining configured email backend
1010instances, replacing :func:`.mail.get_connection`. A new ``using`` argument
1111replaces the earlier ``connection`` in Django functions that send email.
1212
13- The older functionality and settings are still available, but are deprecated
14- and will be removed in Django 7.0. This guide provides details on migrating
15- existing projects to the new mailers functionality.
13+ This guide provides details on migrating existing projects to the new mailers
14+ functionality.
1615
1716All Django projects that send email should:
1817
@@ -36,8 +35,7 @@ All Django projects that send email should:
3635
3736 Consider running with deprecation warnings enabled in production to catch
3837 those deprecations. Or carefully review your code (including third-party
39- packages) for use of any deprecated email features that will change in
40- Django 7.0.
38+ packages) for use of any deprecated email features.
4139
4240Other updates are needed only for projects or reusable Django libraries that
4341use these specific features:
9593
9694.. _deprecated-email-settings:
9795
96+ .. deprecated:: 6.1
97+
98+ The :setting:`EMAIL_BACKEND` and related ``EMAIL_*`` settings are
99+ deprecated.
100+
98101The complete list of deprecated ``EMAIL_*`` settings and where they should be
99102moved in a :setting:`MAILERS` configuration is:
100103
@@ -178,9 +181,10 @@ migration guide for recommended updates.
178181Replacing ``get_connection()`` and ``connection`` arguments
179182-----------------------------------------------------------
180183
181- :func:`.mail.get_connection` is deprecated in Django 6.1, as is the
182- ``connection`` argument for passing backend instances directly to mail
183- functions.
184+ .. deprecated:: 6.1
185+
186+ :func:`.mail.get_connection` and the ``connection`` argument for passing
187+ backend instances directly to mail functions are deprecated.
184188
185189The replacement for ``get_connection()`` depends on how it is being called:
186190
@@ -247,9 +251,11 @@ The replacement for ``get_connection()`` depends on how it is being called:
247251Replacing ``fail_silently``
248252---------------------------
249253
250- The ``fail_silently`` arguments to :func:`.send_mail`, :func:`.send_mass_mail`,
251- :func:`.mail_admins`, :func:`.mail_managers`, and :meth:`.EmailMessage.send`
252- are deprecated.
254+ .. deprecated:: 6.1
255+
256+ The ``fail_silently`` argument to :func:`.send_mail`,
257+ :func:`.send_mass_mail`, :func:`.mail_admins`, :func:`.mail_managers`, and
258+ :meth:`.EmailMessage.send` are deprecated.
253259
254260Existing code using ``fail_silently`` seems to have several different
255261expectations for its behavior, many of which don't match the actual (and email
@@ -327,8 +333,7 @@ This is useful for error messages (e.g., ``raise InvalidMailer(f"Bad host
327333passed to backend init as keyword arguments.
328334
329335For reusable libraries that want to support compatibility with deprecated mail
330- functions and settings (similar to Django's built-in email backends), or that
331- still support Django versions earlier than 6.1:
336+ functions and settings, or that support older Django versions:
332337
333338* A backend can detect it is being initialized without :setting:`MAILERS` by
334339 checking if ``self.alias is None``. (Django's built-in backends check this to
@@ -349,11 +354,14 @@ still support Django versions earlier than 6.1:
349354Replacing ``auth_user`` and ``auth_password``
350355---------------------------------------------
351356
352- The ``auth_user`` and ``auth_password`` arguments to :func:`.send_mail` and
353- :func:`.send_mass_mail` are deprecated. To replace them, define a custom
354- :setting:`MAILERS` configuration with ``"username"`` and ``"password"``
355- :setting:`"OPTIONS" <MAILERS-OPTIONS>`, and refer to that configuration with
356- the ``using`` argument when sending mail.
357+ .. deprecated:: 6.1
358+
359+ The ``auth_user`` and ``auth_password`` arguments to :func:`.send_mail`
360+ and :func:`.send_mass_mail` are deprecated.
361+
362+ To replace them, define a custom :setting:`MAILERS` configuration with
363+ ``"username"`` and ``"password"`` :setting:`"OPTIONS" <MAILERS-OPTIONS>`, and
364+ refer to that configuration with the ``using`` argument when sending mail.
357365
358366For example, to upgrade::
359367
@@ -389,9 +397,13 @@ And then refer to it when sending::
389397Updating AdminEmailHandler ``email_backend``
390398--------------------------------------------
391399
392- The ``email_backend`` argument to the logging :class:`.AdminEmailHandler` is
393- deprecated. Replace it with a custom :setting:`MAILERS` configuration and refer
394- to that configuration with the ``using`` argument.
400+ .. deprecated:: 6.1
401+
402+ The ``email_backend`` argument to the logging :class:`.AdminEmailHandler`
403+ is deprecated.
404+
405+ Replace it with a custom :setting:`MAILERS` configuration and refer to that
406+ configuration with the ``using`` argument.
395407
396408For example, if your settings include::
397409
0 commit comments