Fixed #3307 -- Added BCC support to the EmailMessage class. En-passant, fixed a

number of RST formatting errors in the email docs.


git-svn-id: http://code.djangoproject.com/svn/django/trunk@5146 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 38 insertions, 24 deletions

diff --git a/docs/email.txt b/docs/email.txt
index 56a552bdb7..0196b50679 100644
--- a/docs/email.txt
+++ b/docs/email.txt
@@ -189,42 +189,56 @@ from the request's POST data, sends that to admin@example.com and redirects to
 The EmailMessage and SMTPConnection classes
 ===========================================
 
-Django's `send_mail()` and `send_mass_mail()` functions are actually thin
-wrappers that make use of the `EmailMessage` and `SMTPConnection` classes in
-`django.mail`.  If you ever need to customize the way Django sends email, you
-can subclass these two classes to suit your needs.
+Django's ``send_mail()`` and ``send_mass_mail()`` functions are actually thin
+wrappers that make use of the ``EmailMessage`` and ``SMTPConnection`` classes
+in ``django.mail``.  If you ever need to customize the way Django sends email,
+you can subclass these two classes to suit your needs.
 
 .. note::
-    Not all features of the `EmailMessage` class are available through the
-    `send_mail()` and related wrapper functions. If you wish to use advanced
+    Not all features of the ``EmailMessage`` class are available through the
+    ``send_mail()`` and related wrapper functions. If you wish to use advanced
     features such as including BCC recipients or multi-part email, you will
-    need to create `EmailMessage` instances directly.
+    need to create ``EmailMessage`` instances directly.
 
-In general, `EmailMessage` is responsible for creating the email message
-itself. `SMTPConnection` is responsible for the network connection side of the
-operation. This means you can reuse the same connection (an `SMTPConnection`
-instance) for multiple messages.
+In general, ``EmailMessage`` is responsible for creating the email message
+itself. ``SMTPConnection`` is responsible for the network connection side of
+the operation. This means you can reuse the same connection (an
+``SMTPConnection`` instance) for multiple messages.
 
-The `EmailMessage` class has the following methods that you can use:
+The ``EmailMessage`` class is initialised as follows::
 
- * `send()` sends the message, using either the connection that is specified
-   in the `connection` attribute, or creating a new connection if none already
+    email = EmailMessage(subject, body, from_email, to, bcc, connection)
+
+All of these parameters are optional. If ``from_email`` is omitted, the value
+from ``settings.DEFAULT_FROM_EMAIL`` is used. Both the ``to`` and ``bcc``
+parameters are lists of addresses.
+
+The class has the following methods that you can use:
+
+ * ``send()`` sends the message, using either the connection that is specified
+   in the ``connection`` attribute, or creating a new connection if none already
    exists.
- * `message()` constructs a `django.core.mail.SafeMIMEText` object (a
-   sub-class of Python's `email.MIMEText.MIMEText` class) holding the message
-   to be sent. If you ever need to extend the `EmailMessage` class, you will
-   probably want to override this method to put the content you wish into the
-   MIME object.
+ * ``message()`` constructs a ``django.core.mail.SafeMIMEText`` object (a
+   sub-class of Python's ``email.MIMEText.MIMEText`` class) holding the
+   message to be sent. If you ever need to extend the `EmailMessage` class,
+   you will probably want to override this method to put the content you wish
+   into the MIME object.
+ * ``recipients()`` returns a lists of all the recipients of the message,
+   whether they are recorded in the ``to`` or ``bcc`` attributes. This is
+   another method you need to possibly override when sub-classing, since the
+   SMTP server needs to be told the full list of recipients when the message
+   is sent. If you add another way to specify recipients in your class, they
+   need to be returned from this method as well.
 
-The `SMTPConnection` class is initialized with the host, port, username and
+The ``SMTPConnection`` class is initialized with the host, port, username and
 password for the SMTP server. If you don't specify one or more of those
 options, they are read from your settings file.
 
-If you are sending lots of messages at once, the `send_messages()` method of
-the `SMTPConnection` class will be useful. It takes a list of `EmailMessage`
+If you are sending lots of messages at once, the ``send_messages()`` method of
+the ``SMTPConnection`` class will be useful. It takes a list of ``EmailMessage``
 instances (or sub-classes) and sends them over a single connection. For
-example, if you have a function called `get_notification_email()` that returns a
-list of `EmailMessage` objects representing some periodic email you wish to
+example, if you have a function called ``get_notification_email()`` that returns a
+list of ``EmailMessage`` objects representing some periodic email you wish to
 send out, you could send this with::
 
     connection = SMTPConnection()   # Use default settings for connection