From 80ea222c8af501031b2eae4f7d9fdbf16cb507a7 Mon Sep 17 00:00:00 2001 From: VIZZARD-X Date: Fri, 10 Jul 2026 21:46:16 +0530 Subject: 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> --- docs/ref/settings.txt | 23 +++++++++++++++++++---- docs/releases/6.2.txt | 4 +++- docs/topics/email.txt | 37 ++++++++++++++++++++++++++++++------- 3 files changed, 52 insertions(+), 12 deletions(-) (limited to 'docs') 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" '] 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" `` 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" `` 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 -- cgit v1.3