summaryrefslogtreecommitdiff
path: root/docs/topics/email.txt
AgeCommit message (Collapse)Author
14 daysFixed #37152 -- Raised ValueError when Bcc is used in EmailMessage headers.diaxoaine
Bcc addresses are sent via the SMTP envelope and must never appear in the message itself. A "Bcc" key in `extra_headers` was not excluded like From/To/Cc/Reply-To, so it leaked into the generated message as a visible header. Thanks Mike Edmunds for reviews.
2026-06-16Fixed typo in section "Configuring email" in docs/topics/email.txt.Mike Edmunds
2026-05-20Removed versionadded/changed annotations for 6.0.Sarah Boyce
2026-05-20Refs #35514 -- Cleaned up mailers docs.Mike Edmunds
* Fixed typos related to automated EMAIL_PROVIDERS -> MAILERS renaming. * Clarified wording in some recently added/updated sections. * Removed deprecated, extraneous `fail_silently=False` from examples. * Moved EmailBackend API documentation out of "Email backends" intro into a dedicated section in email.txt. * Sorted MAILERS alphabetically in settings.txt.
2026-05-13Fixed #35514 -- Implemented dictionary-based MAILERS.Mike Edmunds
See DEP 0018. Added: * MAILERS setting. * django.core.mail.mailers dict-like EmailBackend factory. * `using` argument to mail sending APIs. * `sent_using` attribute to mail.outbox messages in locmem backend. * MAILERS in startproject settings template, set to console backend. * AdminLogHandler.using argument. * BrokenLinkEmailsMiddleware.send_mail() method. Updated: * BaseEmailBackend to track the MAILERS alias used to construct it, and to report errors for unknown kwargs (OPTIONS). * EmailBackend implementations to initialize from kwargs (OPTIONS) only when MAILERS is being used. * smtp.EmailBackend to require `host` option and to default `port` option based on SSL/TLS options. * SimpleTestCase setup to substitute the locmem backend for all defined MAILERS configurations. * Django's tests that send mail to define MAILERS. Deprecated: * EMAIL_BACKEND and other backend-related EMAIL_* settings. * mail.get_connection(). * The `connection`, `fail_silently`, `auth_user`, and `auth_password` arguments to mail functions. * The EmailMessage.connection attribute. * BaseEmailBackend support for `fail_silently`. Backends that support fail_silently (SMTP, console, file) now implement it directly. * AdminEmailHandler.email_backend argument. Removed undocumented features without deprecation: * EmailMessage.get_connection() method. (send() now raises an error if a subclass has attempted to override it.) * EmailMessage.send() no longer sets self.connection to the connection used for sending. (It still _uses_ a pre-existing self.connection.) * AdminEmailHandler.connection() method. (Init now raises an error if a subclass has attempted to override it.) Thanks to Natalia Bidart for shepherding DEP 0018 and for extensive reviews and suggestions on the implementation. Thanks to Jacob Rief for the initial implementation and multiple iterations while refining the design. Co-authored-by: Jacob Rief <jacob.rief@gmail.com>
2026-04-16Refs #35514 -- Cleaned up email docs.Mike Edmunds
* Indented get_connection() details into its function block. * Updated introductory paragraph to better reflect current capabilities. * Changed link in "Quick examples" to go to descriptive text rather than reference for send_mail(). * Avoided implying that send_mail() is only reliable "in most cases." * Improved description of development SMTP server. * Expanded information on third-party backends. * Moved "Email backends" introductory paragraph above API methods and expanded it to match section content.
2026-04-16Refs #35514 -- Added "Configuring email" section to email docs.Mike Edmunds
2026-04-16Refs #35514 -- Moved and renamed "Sending multiple emails" in email docs.Mike Edmunds
Moved "Sending multiple emails" from the "Email backends" section to the "Sending messages" section and renamed it to "Sending many messages efficiently" to better reflect its content. Moved the related connection manager example from the "Email backends" intro into the same section.
2026-04-16Refs #35514 -- Moved get_connection() after backends in email docs.Mike Edmunds
Moved "Obtaining an instance of an email backend" after documentation for individual backends (matching similar approach in Tasks docs).
2026-04-15Refs #35514 -- Corrected email backends' outline levels in email docs.Mike Edmunds
Moved documentation section for each email backend to be a direct child of "Email backends" (rather than subsections of "Obtaining an instance of an email backend"). Added a section header for "Third-party backends" to surface it in the outline and separate it from "Dummy backend."
2026-04-15Refs #35514 -- Moved EmailMessage class up in email docs.Mike Edmunds
Moved the "Preventing header injection" discussion below sections on EmailMessage and related classes.
2026-04-15Refs #35514 -- Grouped sending-related features in email docs.Mike Edmunds
Introduced a top-level "Sending messages" section to group together send_mail(), send_mass_mail(), mail_admins(), mail_managers(), the EmailMessage and EmailMultiAlternatives classes, and other topics related to sending.
2026-04-15Refs #35514 -- Moved email docs examples to relevant section.Mike Edmunds
The top-level "Examples" section of docs/topics/email.txt seemed intended to illustrate the difference between send_mail() and send_mass_mail(), not to provide general examples of sending email. Moved it into the existing "send_mass_mail() vs. send_mail()" section. (There's already a "Quick examples" section at the top of the page with general examples.)
2026-04-15Fixed broken link in email docs.Mike Edmunds
2026-04-15Fixed incomplete comment in email docs.Natalia
2026-03-16Corrected signature for EmailMessage.message() in email topics docs.Mike Edmunds
Fixed the EmailMessage.message() method signature in the docs to reinforce that the `policy` argument is keyword-only. (The text already describes it correctly as keyword-only.)
2026-03-16Fixed #36894 -- Added TypeError for conflicting arguments in mail APIs.Praful Gulani
A TypeError is now raised if fail_silently=True, auth_user, or auth_password are provided along a connection. Updated AdminEmailHandler in django.utils.log to remove redundant fail_silently=True. Thanks Mike Edmunds for the report and Jacob Tyler Walls for the review.
2026-02-09Fixed #36908 -- Removed unnecessary "fail_silently" param from quick example ↵SnippyCodes
in docs/topics/email.txt.
2025-12-08Refs #35581 -- Fixed email image inline attachment example.Adam Johnson
1. Added imports and setup for clarity. 2. Removed adding `<` and `>` to Content-ID, as `make_msgid()` already includes them. 3. Removed `$` from reference in HTML, and instead stripped `<>` there, as required by HTML `cid:` references.
2025-11-06Added community package email backends mention to docs.Tim Schilling
Co-authored-by: Clifford Gama <cliffygamy@gmail.com>
2025-09-17Added backticks to email addresses in docs.Mariusz Felisiak
2025-09-17Removed versionadded/changed annotations for 5.2.Jacob Walls
2025-09-15Fixed #36591 -- Removed unnecessary dotted paths in email docs.Dani Fornons
2025-09-12Fixed #36597 -- Corrected directives for functions from email module in docs.Mridul Dhall
Thanks Mike Edmunds for the report.
2025-09-05Fixed #36524 -- Enabled docs cross references to EmailMessage methods.Mike Edmunds
Updated docs for class django.core.mail.EmailMessage to use Sphinx `method::` directives, allowing cross references to those methods elsewhere in the docs. Updated references to those methods in the email docs and 6.0 release notes to link directly to the specific methods.
2025-09-05Removed redundant directive in email docs.Mike Edmunds
docs/topics/email.txt declares `module:: django.core.mail`. Removed unnecessary `currentmodule::` pointing to the same module.
2025-08-28Fixed #36570 -- Removed unnecessary :py domain from documentation roles.SaJH
Signed-off-by: SaJH <wogur981208@gmail.com>
2025-08-25Refs #36485 -- Rewrapped docs to 79 columns line length.David Smith
Lines in the docs files were manually adjusted to conform to the 79 columns limit per line (plus newline), improving readability and consistency across the content.
2025-08-25Refs #36485 -- Removed unnecessary parentheses in :meth: and :func: roles in ↵David Smith
docs.
2025-07-25Fixed #35581 -- Updated django.core.mail to Python's modern email API.Mike Edmunds
- Changed EmailMessage.message() to construct a "modern email API" email.message.EmailMessage and added policy keyword arg. - Added support for modern MIMEPart objects in EmailMessage.attach() (and EmailMessage constructor, EmailMessage.attachments list). - Updated SMTP EmailBackend to use modern email.policy.SMTP. Deprecated: - Attaching MIMEBase objects (replace with MIMEPart) - BadHeaderError (modern email uses ValueError) - SafeMIMEText, SafeMIMEMultipart (unnecessary for modern email) - django.core.mail.forbid_multi_line_headers() (undocumented, but exposed via `__all__` and in wide use) - django.core.mail.message.sanitize_address() (undocumented, but in wide use) Removed without deprecation (all undocumented): - EmailMessage.mixed_subtype - EmailMultiAlternatives.alternative_subtype - Support for setting (undocumented) EmailMessage.encoding property to a legacy email.charset.Charset object Related changes: - Dropped tests for incorrect RFC 2047 encoding of non-ASCII email address localparts. This is specifically prohibited by RFC 2047, and not supported by any known MTA or email client. (Python still mis-applies encoded-word to non-ASCII localparts, but it is a bug that may be fixed in the future.) - Added tests that try to discourage using Python's legacy email APIs in future updates to django.core.mail.
2025-07-25Fixed typo in docs/topics/email.txt.Mike Edmunds
2025-07-17Refs #36163 -- Reordered EmailMessage options in docs/topics/email.txt.Mike Edmunds
Reordered the keyword-only EmailMessage parameters in the documentation to group similar options together and move rarely used options later. Used keywords for *all* parameters in EmailMessage examples to improve clarity.
2025-07-17Fixed #36163 -- Deprecated most positional arguments in django.core.mail.Mike Edmunds
In public mail APIs, changed less frequently used parameters from keyword-or-positional to keyword-only, emitting a warning during the required deprecation period.
2025-07-17Fixed get_connection() signature in docs/topics/email.txt.Mike Edmunds
django.core.mail.get_connection() has always supported only variable keyword arguments (never variable positional arguments).
2025-01-28Refs #36005 -- Bumped minimum supported versions of 3rd-party packages.Mariusz Felisiak
This bumps minimum supported versions of 3rd-party packages to the first releases to support Python 3.12.
2024-10-30Fixed #35864 -- Documented EmailMessage.connection is ignored when using ↵Mike Edmunds
send_messages().
2024-09-11Added example of email sending with additional capabilities to ↵Ronny V.
docs/topics/email.txt. Co-authored-by: Mike Edmunds <medmunds@gmail.com>
2024-08-05Used :pypi: role in docs where appropriate.Mariusz Felisiak
2024-08-05Refs #35537 -- Improved documentation and test coverage for email ↵Jake Howard
attachments and alternatives.
2024-06-21Fixed #35528 -- Added EmailMultiAlternatives.body_contains() helper method.Ronny Vedrilla
2024-06-21Cleaned up EmailMultiAlternatives docs.Sarah Boyce
2024-06-20Fixed #35537 -- Changed EmailMessage.attachments and ↵Jake Howard
EmailMultiAlternatives.alternatives to use namedtuples. This makes it more descriptive to pull out the named fields.
2024-06-18Restructured the EmailMultiAlternatives docs.Sarah Boyce
2023-03-01Fixed #34140 -- Reformatted code blocks in docs with blacken-docs.django-bot
2023-02-10Refs #34140 -- Applied rst code-block to non-Python examples.Carlton Gibson
Thanks to J.V. Zammit, Paolo Melchiorre, and Mariusz Felisiak for reviews.
2022-04-28Added backticks to code literals in various docs.David
2022-02-12Refs #32074 -- Recommended aiosmtpd for minimal SMTP server.Claude Paroz
Follow up to 569a33579c3cca5f801c544d9b52a34e3c779424.
2021-09-21Fixed broken links and redirects in docs.Mariusz Felisiak
2021-08-09Fixed some broken links and redirects in docs.Jacob Walls
2021-07-27Refs #32956 -- Changed "afterwards" to "afterward" in docs and comments.David Smith
This also removes unnecessary comments with the previous spelling. AP Stylebook has a short entry to advise the preferred spelling for "en-us". "Afterwards" is preferred in British English.
generated by cgit v1.3 (git 2.53.0) at 2026-06-30 20:53:47 +0000