Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Browse files

Added docs/email.txt

git-svn-id: bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 0891e7bec50a7d76c95e6098b1b71ae014b64272 1 parent 37f068c
@adrianholovaty adrianholovaty authored
Showing with 110 additions and 0 deletions.
  1. +110 −0 docs/email.txt
110 docs/email.txt
@@ -0,0 +1,110 @@
+Sending e-mail
+Although Python makes sending e-mail relatively easy via the `smtplib library`_,
+Django provides a couple of light wrappers over it, to make sending e-mail
+extra quick.
+The code lives in a single module: ``django.core.mail``.
+.. _smtplib library:
+Quick example
+In two lines::
+ from django.core.mail import send_mail
+ send_mail('Subject here', 'Here is the message.', '',
+ [''], fail_silently=False)
+The send_mail function
+The simplest way to send e-mail is using the function
+``django.core.mail.send_mail``. Here's its definition::
+ send_mail(subject, message, from_email, recipient_list, fail_silently=False)
+All parameters are required except for ``fail_silently``, which is ``False`` by
+ * ``subject``: A string.
+ * ``message``: A string.
+ * ``from_email``: A string.
+ * ``recipient_list``: A list of strings, each an e-mail address. Each
+ member of ``recipient_list`` will see the other recipients in the "To:"
+ field of the e-mail message.
+ * ``fail_silently``: A boolean. If it's ``False``, ``send_mail`` will raise
+ an ``smtplib.SMTPException``. See the `smtplib docs`_ for a list of
+ possible exceptions, all of which are subclasses of ``SMTPException``.
+.. _smtplib docs:
+The send_mass_mail function
+``django.core.mail.send_mass_mail`` is intended to handle mass e-mailing.
+Here's the definition::
+ send_mass_mail(datatuple, fail_silently=False):
+``datatuple`` is a tuple in which each element is in this format::
+ (subject, message, from_email, recipient_list)
+``fail_silently`` has the same function as in ``send_mail()``.
+Each separate element of ``datatuple`` results in a separate e-mail message.
+As in ``send_mail()``, recipients in the same ``recipient_list`` will all see
+the other addresses in the e-mail messages's "To:" field.
+send_mass_mail vs. send_mail
+The main difference between ``send_mass_mail()`` and ``send_mail()`` is that
+``send_mail()`` opens a connection to the mail server each time it's executed,
+while ``send_mass_mail()`` uses a single connection for each of its messages.
+This makes ``send_mass_mail()`` slightly more efficient.
+The mail_admins function
+``django.core.mail.mail_admins`` is a shortcut for sending an e-mail to the
+site admins, as defined in the `ADMINS setting`_. Here's the definition::
+ mail_admins(subject, message, fail_silently=False)
+``mail_admins()`` prefixes the subject with the value of the
+`EMAIL_SUBJECT_PREFIX setting`_, which is ``"[Django] "`` by default.
+.. _ADMINS setting:
+The mail_managers function
+``django.core.mail.mail_managers`` is just like ``mail_admins``, except it
+sends an e-mail to the site managers, as defined in the `MANAGERS setting`_.
+.. _MANAGERS setting:
+This sends a single e-mail to and, with them
+both appearing in the "To:"::
+ send_mail('Subject', 'Message.', '',
+ ['', ''])
+This sends a message to and, with them both
+receiving a separate e-mail::
+ datatuple = (
+ ('Subject', 'Message.', '', [''],
+ ('Subject', 'Message.', '', [''],
+ )
+ send_mass_mail(datatuple)

0 comments on commit 0891e7b

Please sign in to comment.
Something went wrong with that request. Please try again.