From d6e58765f559ba1d02974e11307a25e2e58d1585 Mon Sep 17 00:00:00 2001 From: Mike Edmunds Date: Tue, 7 Apr 2026 12:22:01 -0700 Subject: Refs #35514 -- Moved email docs examples to relevant section. 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.) --- docs/topics/email.txt | 51 +++++++++++++++++++++++++-------------------------- 1 file changed, 25 insertions(+), 26 deletions(-) (limited to 'docs/topics') diff --git a/docs/topics/email.txt b/docs/topics/email.txt index f7f1d12491..7411603e41 100644 --- a/docs/topics/email.txt +++ b/docs/topics/email.txt @@ -180,10 +180,31 @@ The return value will be the number of successfully delivered messages. ``send_mass_mail()`` vs. ``send_mail()`` ---------------------------------------- -The main difference between :func:`send_mass_mail` and :func:`send_mail` is -that :func:`send_mail` opens a connection to the mail server each time it's -executed, while :func:`send_mass_mail` uses a single connection for all of its -messages. This makes :func:`send_mass_mail` slightly more efficient. +The main difference between :func:`send_mass_mail` and repeatedly calling +:func:`send_mail` is that :func:`send_mail` opens a connection to the mail +server each time it's executed, while :func:`send_mass_mail` uses a single +connection for all of its messages. This makes :func:`send_mass_mail` slightly +more efficient. + +:func:`send_mail` with multiple ``to`` addresses sends a single email message, +with ``john@example.com`` and ``jane@example.com`` both appearing in the "To:" +field:: + + send_mail( + "Subject", + "Message.", + "from@example.com", + ["john@example.com", "jane@example.com"], + ) + +:func:`send_mass_mail` sends a separate message per ``datatuple`` element, so +``john@example.com`` and ``jane@example.com`` each receive their own email:: + + datatuple = ( + ("Subject", "Message.", "from@example.com", ["john@example.com"]), + ("Subject", "Message.", "from@example.com", ["jane@example.com"]), + ) + send_mass_mail(datatuple) ``mail_admins()`` ================= @@ -235,28 +256,6 @@ setting. Older versions ignored ``fail_silently=True`` when a ``connection`` was also provided. This now raises a ``TypeError``. -Examples -======== - -This sends a single email to john@example.com and jane@example.com, with them -both appearing in the "To:":: - - send_mail( - "Subject", - "Message.", - "from@example.com", - ["john@example.com", "jane@example.com"], - ) - -This sends a message to ``john@example.com`` and ``jane@example.com``, with -them both receiving a separate email:: - - datatuple = ( - ("Subject", "Message.", "from@example.com", ["john@example.com"]), - ("Subject", "Message.", "from@example.com", ["jane@example.com"]), - ) - send_mass_mail(datatuple) - Preventing header injection =========================== -- cgit v1.3