Django

Code

Changeset 5146

Show
Ignore:
Timestamp:
05/03/07 09:38:45 (2 years ago)
Author:
mtredinnick
Message:

Fixed #3307 -- Added BCC support to the EmailMessage? class. En-passant, fixed a
number of RST formatting errors in the email docs.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • django/trunk/django/core/mail.py

    r5145 r5146  
    143143        try: 
    144144            self.connection.sendmail(email_message.from_email, 
    145                     email_message.to, email_message.message().as_string()) 
     145                    email_message.recipients(), 
     146                    email_message.message().as_string()) 
    146147        except: 
    147148            if not self.fail_silently: 
    …… 
    154155    A container for email information. 
    155156    """ 
    156     def __init__(self, subject='', body='', from_email=None, to=None, connection=None): 
     157    def __init__(self, subject='', body='', from_email=None, to=None, bcc=None, connection=None): 
    157158        self.to = to or [] 
    158         if from_email is None: 
    159             self.from_email = settings.DEFAULT_FROM_EMAIL 
    160         else: 
    161             self.from_email = from_email 
     159        self.bcc = bcc or [] 
     160        self.from_email = from_email or settings.DEFAULT_FROM_EMAIL 
    162161        self.subject = subject 
    163162        self.body = body 
    …… 
    176175        msg['Date'] = formatdate() 
    177176        msg['Message-ID'] = make_msgid() 
     177        if self.bcc: 
     178            msg['Bcc'] = ', '.join(self.bcc) 
    178179        return msg 
     180 
     181    def recipients(self): 
     182        """ 
     183        Returns a list of all recipients of the email (includes direct 
     184        addressees as well as Bcc entries). 
     185        """ 
     186        return self.to + self.bcc 
    179187 
    180188    def send(self, fail_silently=False): 

  • django/trunk/docs/email.txt

    r5144 r5146  
    190190=========================================== 
    191191 
    192 Django's `send_mail()` and `send_mass_mail()` functions are actually thin 
    193 wrappers that make use of the `EmailMessage` and `SMTPConnection` classes in 
    194 `django.mail`.  If you ever need to customize the way Django sends email, you 
    195 can subclass these two classes to suit your needs. 
     192Django's ``send_mail()`` and ``send_mass_mail()`` functions are actually thin 
     193wrappers that make use of the ``EmailMessage`` and ``SMTPConnection`` classes 
     194in ``django.mail``.  If you ever need to customize the way Django sends email, 
     195you can subclass these two classes to suit your needs. 
    196196 
    197197.. note:: 
    198     Not all features of the `EmailMessage` class are available through the 
    199     `send_mail()` and related wrapper functions. If you wish to use advanced 
     198    Not all features of the ``EmailMessage`` class are available through the 
     199    ``send_mail()`` and related wrapper functions. If you wish to use advanced 
    200200    features such as including BCC recipients or multi-part email, you will 
    201     need to create `EmailMessage` instances directly. 
    202  
    203 In general, `EmailMessage` is responsible for creating the email message 
    204 itself. `SMTPConnection` is responsible for the network connection side of the 
    205 operation. This means you can reuse the same connection (an `SMTPConnection` 
    206 instance) for multiple messages. 
    207  
    208 The `EmailMessage` class has the following methods that you can use: 
    209  
    210  * `send()` sends the message, using either the connection that is specified 
    211    in the `connection` attribute, or creating a new connection if none already 
     201    need to create ``EmailMessage`` instances directly. 
     202 
     203In general, ``EmailMessage`` is responsible for creating the email message 
     204itself. ``SMTPConnection`` is responsible for the network connection side of 
     205the operation. This means you can reuse the same connection (an 
     206``SMTPConnection`` instance) for multiple messages. 
     207 
     208The ``EmailMessage`` class is initialised as follows:: 
     209 
     210    email = EmailMessage(subject, body, from_email, to, bcc, connection) 
     211 
     212All of these parameters are optional. If ``from_email`` is omitted, the value 
     213from ``settings.DEFAULT_FROM_EMAIL`` is used. Both the ``to`` and ``bcc`` 
     214parameters are lists of addresses. 
     215 
     216The class has the following methods that you can use: 
     217 
     218 * ``send()`` sends the message, using either the connection that is specified 
     219   in the ``connection`` attribute, or creating a new connection if none already 
    212220   exists. 
    213  * `message()` constructs a `django.core.mail.SafeMIMEText` object (a 
    214    sub-class of Python's `email.MIMEText.MIMEText` class) holding the message 
    215    to be sent. If you ever need to extend the `EmailMessage` class, you will 
    216    probably want to override this method to put the content you wish into the 
    217    MIME object. 
    218  
    219 The `SMTPConnection` class is initialized with the host, port, username and 
     221 * ``message()`` constructs a ``django.core.mail.SafeMIMEText`` object (a 
     222   sub-class of Python's ``email.MIMEText.MIMEText`` class) holding the 
     223   message to be sent. If you ever need to extend the `EmailMessage` class, 
     224   you will probably want to override this method to put the content you wish 
     225   into the MIME object. 
     226 * ``recipients()`` returns a lists of all the recipients of the message, 
     227   whether they are recorded in the ``to`` or ``bcc`` attributes. This is 
     228   another method you need to possibly override when sub-classing, since the 
     229   SMTP server needs to be told the full list of recipients when the message 
     230   is sent. If you add another way to specify recipients in your class, they 
     231   need to be returned from this method as well. 
     232 
     233The ``SMTPConnection`` class is initialized with the host, port, username and 
    220234password for the SMTP server. If you don't specify one or more of those 
    221235options, they are read from your settings file. 
    222236 
    223 If you are sending lots of messages at once, the `send_messages()` method of 
    224 the `SMTPConnection` class will be useful. It takes a list of `EmailMessage` 
     237If you are sending lots of messages at once, the ``send_messages()`` method of 
     238the ``SMTPConnection`` class will be useful. It takes a list of ``EmailMessage`` 
    225239instances (or sub-classes) and sends them over a single connection. For 
    226 example, if you have a function called `get_notification_email()` that returns a 
    227 list of `EmailMessage` objects representing some periodic email you wish to 
     240example, if you have a function called ``get_notification_email()`` that returns a 
     241list of ``EmailMessage`` objects representing some periodic email you wish to 
    228242send out, you could send this with:: 
    229243