From 5ff1d96a523f681b15f679ba771d6c3e2e8e8c49 Mon Sep 17 00:00:00 2001 From: Malcolm Tredinnick Date: Thu, 3 May 2007 14:38:45 +0000 Subject: [PATCH] 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 --- django/core/mail.py | 20 ++++++++++----- docs/email.txt | 62 +++++++++++++++++++++++++++------------------ 2 files changed, 52 insertions(+), 30 deletions(-) diff --git a/django/core/mail.py b/django/core/mail.py index 336d1099df..8661d84287 100644 --- a/django/core/mail.py +++ b/django/core/mail.py @@ -142,7 +142,8 @@ class SMTPConnection(object): 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 @@ class EmailMessage(object): 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]) 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