Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Fixed #3307 -- Added BCC support to the EmailMessage class. En-passan…

…t, 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
  • Loading branch information...
commit 5ff1d96a523f681b15f679ba771d6c3e2e8e8c49 1 parent bc6535b
@malcolmt malcolmt authored
Showing with 53 additions and 31 deletions.
  1. +14 −6 django/core/mail.py
  2. +39 −25 docs/email.txt
View
20 django/core/mail.py
@@ -142,7 +142,8 @@ def _send(self, email_message):
return False
try:
self.connection.sendmail(email_message.from_email,
- email_message.to, email_message.message().as_string())
+ email_message.recipients(),
+ email_message.message().as_string())
except:
if not self.fail_silently:
raise
@@ -153,12 +154,10 @@ class EmailMessage(object):
"""
A container for email information.
"""
- def __init__(self, subject='', body='', from_email=None, to=None, connection=None):
+ def __init__(self, subject='', body='', from_email=None, to=None, bcc=None, connection=None):
self.to = to or []
- if from_email is None:
- self.from_email = settings.DEFAULT_FROM_EMAIL
- else:
- self.from_email = from_email
+ self.bcc = bcc or []
+ self.from_email = from_email or settings.DEFAULT_FROM_EMAIL
self.subject = subject
self.body = body
self.connection = connection
@@ -175,8 +174,17 @@ def message(self):
msg['To'] = ', '.join(self.to)
msg['Date'] = formatdate()
msg['Message-ID'] = make_msgid()
+ if self.bcc:
+ msg['Bcc'] = ', '.join(self.bcc)
return msg
+ def recipients(self):
+ """
+ Returns a list of all recipients of the email (includes direct
+ addressees as well as Bcc entries).
+ """
+ return self.to + self.bcc
+
def send(self, fail_silently=False):
"""Send the email message."""
return self.get_connection(fail_silently).send_messages([self])
View
64 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
- 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.
+ 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 `SMTPConnection` class is initialized with the host, port, username and
+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.
+ * ``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
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

0 comments on commit 5ff1d96

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