summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorVIZZARD-X <vigneshanandmay13@gmail.com>2026-07-10 21:46:16 +0530
committernessita <124304+nessita@users.noreply.github.com>2026-10-01 11:36:13 -0300
commit80ea222c8af501031b2eae4f7d9fdbf16cb507a7 (patch)
treecc613b1df06f20f62204133980186ff676725e64 /docs
parent23e8bcc464e5faefec28bf36a2f4610a5e7f4be5 (diff)
Fixed #37167 -- Allowed email.headerregistry.Address objects as email addresses.
Address is the safe way to build an email address with a display name from variable parts (see #34753), but `ADMINS` and `MANAGERS` rejected non-string values, so it could not be used there. This branch allows `Address` instances in those settings, documents, and tests the support already present in `DEFAULT_FROM_EMAIL`, `SERVER_EMAIL`, `send_mail()`, `send_mass_mail()`, and `EmailMessage`. Co-authored-by: Natalia <124304+nessita@users.noreply.github.com>
Diffstat (limited to 'docs')
-rw-r--r--docs/ref/settings.txt23
-rw-r--r--docs/releases/6.2.txt4
-rw-r--r--docs/topics/email.txt37
3 files changed, 52 insertions, 12 deletions
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 304bb75ca3..674f676013 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -52,14 +52,17 @@ A list of all the people who get code error notifications. When
is configured in :setting:`LOGGING` (done by default), Django emails these
people the details of exceptions raised in the request/response cycle.
-Each item in the list should be an email address string. Example::
+Each item in the list should be an email address string or
+:class:`~email.headerregistry.Address` object. Example::
ADMINS = ["john@example.com", '"Ng, Mary" <mary@example.com>']
To safely build an address with a display name from variable content, see
-:ref:`formatting-addresses`, which recommends using
-:class:`~email.headerregistry.Address` over string formatting, but since this
-setting requires a list of strings, wrap each ``Address`` in ``str(...)``.
+:ref:`formatting-addresses`.
+
+.. versionchanged:: 6.2
+
+ Support for :class:`~email.headerregistry.Address` objects was added.
.. setting:: ALLOWED_HOSTS
@@ -1359,6 +1362,10 @@ This doesn't affect error messages sent to :setting:`ADMINS` and
To build an address with a display name from variable content, see
:ref:`formatting-addresses`.
+.. versionchanged:: 6.2
+
+ Support for :class:`~email.headerregistry.Address` objects was added.
+
.. setting:: DEFAULT_INDEX_TABLESPACE
``DEFAULT_INDEX_TABLESPACE``
@@ -2250,6 +2257,10 @@ A list in the same format as :setting:`ADMINS` that specifies who should get
broken link notifications when
:class:`~django.middleware.common.BrokenLinkEmailsMiddleware` is enabled.
+.. versionchanged:: 6.2
+
+ Support for :class:`~email.headerregistry.Address` objects was added.
+
.. setting:: MEDIA_ROOT
``MEDIA_ROOT``
@@ -2818,6 +2829,10 @@ To build an address with a display name from variable content, see
regular email messages sent with :func:`~django.core.mail.send_mail`
come from; for that, see :setting:`DEFAULT_FROM_EMAIL`.
+.. versionchanged:: 6.2
+
+ Support for :class:`~email.headerregistry.Address` objects was added.
+
.. setting:: SHORT_DATE_FORMAT
``SHORT_DATE_FORMAT``
diff --git a/docs/releases/6.2.txt b/docs/releases/6.2.txt
index 31eb7a33f0..5d57f7838b 100644
--- a/docs/releases/6.2.txt
+++ b/docs/releases/6.2.txt
@@ -147,7 +147,9 @@ Decorators
Email
~~~~~
-* ...
+* The :setting:`ADMINS`, :setting:`DEFAULT_FROM_EMAIL`, :setting:`MANAGERS`,
+ and :setting:`SERVER_EMAIL` settings now support
+ :class:`~email.headerregistry.Address` objects.
Error Reporting
~~~~~~~~~~~~~~~
diff --git a/docs/topics/email.txt b/docs/topics/email.txt
index f2bda1bda8..baf10a03d9 100644
--- a/docs/topics/email.txt
+++ b/docs/topics/email.txt
@@ -223,11 +223,13 @@ are required.
* ``subject``: A string.
* ``message``: A string.
-* ``from_email``: A string. If ``None``, Django will use the value of the
+* ``from_email``: A string or :class:`~email.headerregistry.Address` object.
+ If ``None``, Django will use the value of the
:setting:`DEFAULT_FROM_EMAIL` setting.
-* ``recipient_list``: A list of strings, each an email address. Each
- member of ``recipient_list`` will see the other recipients in the "To:"
- field of the email message.
+* ``recipient_list``: A list of strings or
+ :class:`~email.headerregistry.Address` objects, each an email address.
+ Each member of ``recipient_list`` will see the other recipients in the
+ "To:" field of the email message.
The following parameters are optional, and must be given as keyword arguments
if used.
@@ -280,6 +282,11 @@ can be ``0`` or ``1`` since it can only send one message).
and ``auth_password`` when a ``connection`` was also provided.
This now raises a ``TypeError``.
+.. versionchanged:: 6.2
+
+ The ``from_email`` and ``recipient_list`` arguments now support
+ :class:`~email.headerregistry.Address` objects in place of strings.
+
``send_mass_mail()``
--------------------
@@ -291,6 +298,9 @@ can be ``0`` or ``1`` since it can only send one message).
(subject, message, from_email, recipient_list)
+``from_email`` and ``recipient_list`` accept the same values as in
+:func:`send_mail`, including :class:`~email.headerregistry.Address` objects.
+
``fail_silently``, ``auth_user``, ``auth_password`` and ``connection`` have the
same functions as in :func:`send_mail`. They must be given as keyword arguments
if used, and are not allowed with the ``using`` argument.
@@ -345,6 +355,11 @@ The return value will be the number of successfully delivered messages.
and ``auth_password`` when a ``connection`` was also provided.
This now raises a ``TypeError``.
+.. versionchanged:: 6.2
+
+ The ``from_email`` and ``recipient_list`` arguments now support
+ :class:`~email.headerregistry.Address` objects in place of strings.
+
``send_mass_mail()`` vs. ``send_mail()``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -494,12 +509,14 @@ email backend API :ref:`provides an alternative
* ``body``: The body text. This should be a plain text message.
- * ``from_email``: The sender's address. Both ``fred@example.com`` and
- ``"Fred" <fred@example.com>`` forms are supported (see
+ * ``from_email``: The sender's address, as a string or
+ :class:`~email.headerregistry.Address` object. Both ``fred@example.com``
+ and ``"Fred" <fred@example.com>`` forms are supported (see
:ref:`formatting-addresses`). If omitted, the
:setting:`DEFAULT_FROM_EMAIL` setting is used.
- * ``to``: A list or tuple of recipient addresses.
+ * ``to``: A list or tuple of recipient addresses, each a string or
+ :class:`~email.headerregistry.Address` object.
The following parameters must be given as keyword arguments if used:
@@ -544,6 +561,12 @@ email backend API :ref:`provides an alternative
Passing all except the first four parameters as positional arguments is
deprecated.
+ .. versionchanged:: 6.2
+
+ The ``from_email``, ``to``, ``cc``, ``bcc``, and ``reply_to`` arguments
+ now support :class:`~email.headerregistry.Address` objects in place of
+ strings.
+
For example::
from django.core.mail import EmailMessage