Fixed #3985 -- Added support for custom email headers.

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

1 files changed, 29 insertions, 10 deletions

diff --git a/docs/email.txt b/docs/email.txt
index 16cf44014c..d81a49c2e2 100644
--- a/docs/email.txt
+++ b/docs/email.txt
@@ -218,22 +218,41 @@ the operation. This means you can reuse the same connection (an
 E-mail messages
 ----------------
 
-The ``EmailMessage`` class is initialized as follows::
+The ``EmailMessage`` class is initialized with the following parameters (in
+the given order, if positional arguments are used). All parameters are
+optional and can be set at any time prior to calling the ``send()`` method.
 
-    email = EmailMessage(subject, body, from_email, to,
-                         bcc, connection, attachments)
+    * ``subject``: The subject line of the e-mail.
 
-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, as strings. The ``attachments`` parameter is
-a list containing either ``(filename, content, mimetype)`` triples of
-``email.MIMEBase.MIMEBase`` instances.
+    * ``body``: The body text. This should be a plain text message.
+
+    * ``from_email``: The sender's address. Both ``fred@example.com`` and
+      ``Fred <fred@example.com>`` forms are legal. If omitted, the
+      ``DEFAULT_FROM_EMAIL`` setting is used.
+
+    * ``to``: A list or tuple of recipient addresses.
+
+    * ``bcc``: A list or tuple of addresses used in the "Bcc" header when
+      sending the e-mail.
+
+    * ``connection``: An ``SMTPConnection`` instance. Use this parameter if
+      you want to use the same conneciton for multiple messages. If omitted, a
+      new connection is created when ``send()`` is called.
+
+    * ``attachments``: A list of attachments to put on the message. These can
+      be either ``email.MIMEBase.MIMEBase`` instances, or ``(filename,
+      content, mimetype)`` triples.
+
+    * ``headers``: A dictionary of extra headers to put on the message. The
+      keys are the header name, values are the header values. It is up to the
+      caller to ensure header names and values are in the correct format for
+      an e-mail message.
 
 For example::
 
     email = EmailMessage('Hello', 'Body goes here', 'from@example.com',
-                ['to1@example.com', 'to2@example.com'],
-                ['bcc@example.com'])
+                ['to1@example.com', 'to2@example.com'], ['bcc@example.com'],
+                headers = {'Reply-To: 'another@example.com'})
 
 The class has the following methods: