Django

Code

Ticket #10355: email_backends.2.diff

File email_backends.2.diff, 60.6 kB (added by andialbrecht, 7 months ago)

  • a/django/conf/global_settings.py

    old new  
    131131DATABASE_PORT = ''             # Set to empty string for default. Not used with sqlite3. 
    132132DATABASE_OPTIONS = {}          # Set to empty dictionary for default. 
    133133 
     134# The email backend to use. For possible shortcuts see django.core.mail. 
     135# The default is to use the 'smtp' backend for sending emails using a 
     136# SMTP server. 
     137# Third-party backends could be configured by a Python import path. 
     138EMAIL_BACKEND = 'smtp' 
     139 
    134140# Host for sending e-mail. 
    135141EMAIL_HOST = 'localhost' 
    136142 
    …… 
    142148EMAIL_HOST_PASSWORD = '' 
    143149EMAIL_USE_TLS = False 
    144150 
     151# Directory for saving messages when using the file backend. 
     152EMAIL_FILE_PATH = None 
     153 
    145154# List of strings representing installed apps. 
    146155INSTALLED_APPS = () 
    147156 

  • /dev/null

    old new  
    1 """ 
    2 Tools for sending email. 
    3 """ 
    4  
    5 import mimetypes 
    6 import os 
    7 import smtplib 
    8 import socket 
    9 import time 
    10 import random 
    11 from email import Charset, Encoders 
    12 from email.MIMEText import MIMEText 
    13 from email.MIMEMultipart import MIMEMultipart 
    14 from email.MIMEBase import MIMEBase 
    15 from email.Header import Header 
    16 from email.Utils import formatdate, parseaddr, formataddr 
    17  
    18 from django.conf import settings 
    19 from django.utils.encoding import smart_str, force_unicode 
    20  
    21 # Don't BASE64-encode UTF-8 messages so that we avoid unwanted attention from 
    22 # some spam filters. 
    23 Charset.add_charset('utf-8', Charset.SHORTEST, Charset.QP, 'utf-8') 
    24  
    25 # Default MIME type to use on attachments (if it is not explicitly given 
    26 # and cannot be guessed). 
    27 DEFAULT_ATTACHMENT_MIME_TYPE = 'application/octet-stream' 
    28  
    29 # Cache the hostname, but do it lazily: socket.getfqdn() can take a couple of 
    30 # seconds, which slows down the restart of the server. 
    31 class CachedDnsName(object): 
    32     def __str__(self): 
    33         return self.get_fqdn() 
    34  
    35     def get_fqdn(self): 
    36         if not hasattr(self, '_fqdn'): 
    37             self._fqdn = socket.getfqdn() 
    38         return self._fqdn 
    39  
    40 DNS_NAME = CachedDnsName() 
    41  
    42 # Copied from Python standard library, with the following modifications: 
    43 # * Used cached hostname for performance. 
    44 # * Added try/except to support lack of getpid() in Jython (#5496). 
    45 def make_msgid(idstring=None): 
    46     """Returns a string suitable for RFC 2822 compliant Message-ID, e.g: 
    47  
    48     <20020201195627.33539.96671@nightshade.la.mastaler.com> 
    49  
    50     Optional idstring if given is a string used to strengthen the 
    51     uniqueness of the message id. 
    52     """ 
    53     timeval = time.time() 
    54     utcdate = time.strftime('%Y%m%d%H%M%S', time.gmtime(timeval)) 
    55     try: 
    56         pid = os.getpid() 
    57     except AttributeError: 
    58         # No getpid() in Jython, for example. 
    59         pid = 1 
    60     randint = random.randrange(100000) 
    61     if idstring is None: 
    62         idstring = '' 
    63     else: 
    64         idstring = '.' + idstring 
    65     idhost = DNS_NAME 
    66     msgid = '<%s.%s.%s%s@%s>' % (utcdate, pid, randint, idstring, idhost) 
    67     return msgid 
    68  
    69 class BadHeaderError(ValueError): 
    70     pass 
    71  
    72 def forbid_multi_line_headers(name, val): 
    73     """Forbids multi-line headers, to prevent header injection.""" 
    74     val = force_unicode(val) 
    75     if '\n' in val or '\r' in val: 
    76         raise BadHeaderError("Header values can't contain newlines (got %r for header %r)" % (val, name)) 
    77     try: 
    78         val = val.encode('ascii') 
    79     except UnicodeEncodeError: 
    80         if name.lower() in ('to', 'from', 'cc'): 
    81             result = [] 
    82             for item in val.split(', '): 
    83                 nm, addr = parseaddr(item) 
    84                 nm = str(Header(nm, settings.DEFAULT_CHARSET)) 
    85                 result.append(formataddr((nm, str(addr)))) 
    86             val = ', '.join(result) 
    87         else: 
    88             val = Header(val, settings.DEFAULT_CHARSET) 
    89     else: 
    90         if name.lower() == 'subject': 
    91             val = Header(val) 
    92     return name, val 
    93  
    94 class SafeMIMEText(MIMEText): 
    95     def __setitem__(self, name, val): 
    96         name, val = forbid_multi_line_headers(name, val) 
    97         MIMEText.__setitem__(self, name, val) 
    98  
    99 class SafeMIMEMultipart(MIMEMultipart): 
    100     def __setitem__(self, name, val): 
    101         name, val = forbid_multi_line_headers(name, val) 
    102         MIMEMultipart.__setitem__(self, name, val) 
    103  
    104 class SMTPConnection(object): 
    105     """ 
    106     A wrapper that manages the SMTP network connection. 
    107     """ 
    108  
    109     def __init__(self, host=None, port=None, username=None, password=None, 
    110                  use_tls=None, fail_silently=False): 
    111         self.host = host or settings.EMAIL_HOST 
    112         self.port = port or settings.EMAIL_PORT 
    113         self.username = username or settings.EMAIL_HOST_USER 
    114         self.password = password or settings.EMAIL_HOST_PASSWORD 
    115         self.use_tls = (use_tls is not None) and use_tls or settings.EMAIL_USE_TLS 
    116         self.fail_silently = fail_silently 
    117         self.connection = None 
    118  
    119     def open(self): 
    120         """ 
    121         Ensures we have a connection to the email server. Returns whether or 
    122         not a new connection was required (True or False). 
    123         """ 
    124         if self.connection: 
    125             # Nothing to do if the connection is already open. 
    126             return False 
    127         try: 
    128             # If local_hostname is not specified, socket.getfqdn() gets used. 
    129             # For performance, we use the cached FQDN for local_hostname. 
    130             self.connection = smtplib.SMTP(self.host, self.port, 
    131                                            local_hostname=DNS_NAME.get_fqdn()) 
    132             if self.use_tls: 
    133                 self.connection.ehlo() 
    134                 self.connection.starttls() 
    135                 self.connection.ehlo() 
    136             if self.username and self.password: 
    137                 self.connection.login(self.username, self.password) 
    138             return True 
    139         except: 
    140             if not self.fail_silently: 
    141                 raise 
    142  
    143     def close(self): 
    144         """Closes the connection to the email server.""" 
    145         try: 
    146             try: 
    147                 self.connection.quit() 
    148             except socket.sslerror: 
    149                 # This happens when calling quit() on a TLS connection 
    150                 # sometimes. 
    151                 self.connection.close() 
    152             except: 
    153                 if self.fail_silently: 
    154                     return 
    155                 raise 
    156         finally: 
    157             self.connection = None 
    158  
    159     def send_messages(self, email_messages): 
    160         """ 
    161         Sends one or more EmailMessage objects and returns the number of email 
    162         messages sent. 
    163         """ 
    164         if not email_messages: 
    165             return 
    166         new_conn_created = self.open() 
    167         if not self.connection: 
    168             # We failed silently on open(). Trying to send would be pointless. 
    169             return 
    170         num_sent = 0 
    171         for message in email_messages: 
    172             sent = self._send(message) 
    173             if sent: 
    174                 num_sent += 1 
    175         if new_conn_created: 
    176             self.close() 
    177         return num_sent 
    178  
    179     def _send(self, email_message): 
    180         """A helper method that does the actual sending.""" 
    181         if not email_message.recipients(): 
    182             return False 
    183         try: 
    184             self.connection.sendmail(email_message.from_email, 
    185                     email_message.recipients(), 
    186                     email_message.message().as_string()) 
    187         except: 
    188             if not self.fail_silently: 
    189                 raise 
    190             return False 
    191         return True 
    192  
    193 class EmailMessage(object): 
    194     """ 
    195     A container for email information. 
    196     """ 
    197     content_subtype = 'plain' 
    198     mixed_subtype = 'mixed' 
    199     encoding = None     # None => use settings default 
    200  
    201     def __init__(self, subject='', body='', from_email=None, to=None, bcc=None, 
    202             connection=None, attachments=None, headers=None): 
    203         """ 
    204         Initialize a single email message (which can be sent to multiple 
    205         recipients). 
    206  
    207         All strings used to create the message can be unicode strings (or UTF-8 
    208         bytestrings). The SafeMIMEText class will handle any necessary encoding 
    209         conversions. 
    210         """ 
    211         if to: 
    212             assert not isinstance(to, basestring), '"to" argument must be a list or tuple' 
    213             self.to = list(to) 
    214         else: 
    215             self.to = [] 
    216         if bcc: 
    217             assert not isinstance(bcc, basestring), '"bcc" argument must be a list or tuple' 
    218             self.bcc = list(bcc) 
    219         else: 
    220             self.bcc = [] 
    221         self.from_email = from_email or settings.DEFAULT_FROM_EMAIL 
    222         self.subject = subject 
    223         self.body = body 
    224         self.attachments = attachments or [] 
    225         self.extra_headers = headers or {} 
    226         self.connection = connection 
    227  
    228     def get_connection(self, fail_silently=False): 
    229         if not self.connection: 
    230             self.connection = SMTPConnection(fail_silently=fail_silently) 
    231         return self.connection 
    232  
    233     def message(self): 
    234         encoding = self.encoding or settings.DEFAULT_CHARSET 
    235         msg = SafeMIMEText(smart_str(self.body, settings.DEFAULT_CHARSET), 
    236                            self.content_subtype, encoding) 
    237         msg = self._create_message(msg) 
    238         msg['Subject'] = self.subject 
    239         msg['From'] = self.extra_headers.pop('From', self.from_email) 
    240         msg['To'] = ', '.join(self.to) 
    241  
    242         # Email header names are case-insensitive (RFC 2045), so we have to 
    243         # accommodate that when doing comparisons. 
    244         header_names = [key.lower() for key in self.extra_headers] 
    245         if 'date' not in header_names: 
    246             msg['Date'] = formatdate() 
    247         if 'message-id' not in header_names: 
    248             msg['Message-ID'] = make_msgid() 
    249         for name, value in self.extra_headers.items(): 
    250             msg[name] = value 
    251         return msg 
    252  
    253     def recipients(self): 
    254         """ 
    255         Returns a list of all recipients of the email (includes direct 
    256         addressees as well as Bcc entries). 
    257         """ 
    258         return self.to + self.bcc 
    259  
    260     def send(self, fail_silently=False): 
    261         """Sends the email message.""" 
    262         if not self.recipients(): 
    263             # Don't bother creating the network connection if there's nobody to 
    264             # send to. 
    265             return 0 
    266         return self.get_connection(fail_silently).send_messages([self]) 
    267  
    268     def attach(self, filename=None, content=None, mimetype=None): 
    269         """ 
    270         Attaches a file with the given filename and content. The filename can 
    271         be omitted and the mimetype is guessed, if not provided. 
    272  
    273         If the first parameter is a MIMEBase subclass it is inserted directly 
    274         into the resulting message attachments. 
    275         """ 
    276         if isinstance(filename, MIMEBase): 
    277             assert content == mimetype == None 
    278             self.attachments.append(filename) 
    279         else: 
    280             assert content is not None 
    281             self.attachments.append((filename, content, mimetype)) 
    282  
    283     def attach_file(self, path, mimetype=None): 
    284         """Attaches a file from the filesystem.""" 
    285         filename = os.path.basename(path) 
    286         content = open(path, 'rb').read() 
    287         self.attach(filename, content, mimetype) 
    288  
    289     def _create_message(self, msg): 
    290         return self._create_attachments(msg) 
    291  
    292     def _create_attachments(self, msg): 
    293         if self.attachments: 
    294             body_msg = msg 
    295             msg = SafeMIMEMultipart(_subtype=self.mixed_subtype) 
    296             if self.body: 
    297                 msg.attach(body_msg) 
    298             for attachment in self.attachments: 
    299                 if isinstance(attachment, MIMEBase): 
    300                     msg.attach(attachment) 
    301                 else: 
    302                     msg.attach(self._create_attachment(*attachment)) 
    303         return msg 
    304  
    305     def _create_mime_attachment(self, content, mimetype): 
    306         """ 
    307         Converts the content, mimetype pair into a MIME attachment object. 
    308         """ 
    309         basetype, subtype = mimetype.split('/', 1) 
    310         if basetype == 'text': 
    311             attachment = SafeMIMEText(smart_str(content, 
    312                 settings.DEFAULT_CHARSET), subtype, settings.DEFAULT_CHARSET) 
    313         else: 
    314             # Encode non-text attachments with base64. 
    315             attachment = MIMEBase(basetype, subtype) 
    316             attachment.set_payload(content) 
    317             Encoders.encode_base64(attachment) 
    318         return attachment 
    319  
    320     def _create_attachment(self, filename, content, mimetype=None): 
    321         """ 
    322         Converts the filename, content, mimetype triple into a MIME attachment 
    323         object. 
    324         """ 
    325         if mimetype is None: 
    326             mimetype, _ = mimetypes.guess_type(filename) 
    327             if mimetype is None: 
    328                 mimetype = DEFAULT_ATTACHMENT_MIME_TYPE 
    329         attachment = self._create_mime_attachment(content, mimetype) 
    330         if filename: 
    331             attachment.add_header('Content-Disposition', 'attachment', 
    332                                   filename=filename) 
    333         return attachment 
    334  
    335 class EmailMultiAlternatives(EmailMessage): 
    336     """ 
    337     A version of EmailMessage that makes it easy to send multipart/alternative 
    338     messages. For example, including text and HTML versions of the text is 
    339     made easier. 
    340     """ 
    341     alternative_subtype = 'alternative' 
    342  
    343     def __init__(self, subject='', body='', from_email=None, to=None, bcc=None, 
    344             connection=None, attachments=None, headers=None, alternatives=None): 
    345         """ 
    346         Initialize a single email message (which can be sent to multiple 
    347         recipients). 
    348  
    349         All strings used to create the message can be unicode strings (or UTF-8 
    350         bytestrings). The SafeMIMEText class will handle any necessary encoding 
    351         conversions. 
    352         """ 
    353         super(EmailMultiAlternatives, self).__init__(subject, body, from_email, to, bcc, connection, attachments, headers) 
    354         self.alternatives=alternatives or [] 
    355  
    356     def attach_alternative(self, content, mimetype): 
    357         """Attach an alternative content representation.""" 
    358         assert content is not None 
    359         assert mimetype is not None 
    360         self.alternatives.append((content, mimetype)) 
    361  
    362     def _create_message(self, msg): 
    363         return self._create_attachments(self._create_alternatives(msg)) 
    364  
    365     def _create_alternatives(self, msg): 
    366         if self.alternatives: 
    367             body_msg = msg 
    368             msg = SafeMIMEMultipart(_subtype=self.alternative_subtype) 
    369             if self.body: 
    370                 msg.attach(body_msg) 
    371             for alternative in self.alternatives: 
    372                 msg.attach(self._create_mime_attachment(*alternative)) 
    373         return msg 
    374  
    375 def send_mail(subject, message, from_email, recipient_list, 
    376               fail_silently=False, auth_user=None, auth_password=None): 
    377     """ 
    378     Easy wrapper for sending a single message to a recipient list. All members 
    379     of the recipient list will see the other recipients in the 'To' field. 
    380  
    381     If auth_user is None, the EMAIL_HOST_USER setting is used. 
    382     If auth_password is None, the EMAIL_HOST_PASSWORD setting is used. 
    383  
    384     Note: The API for this method is frozen. New code wanting to extend the 
    385     functionality should use the EmailMessage class directly. 
    386     """ 
    387     connection = SMTPConnection(username=auth_user, password=auth_password, 
    388                                 fail_silently=fail_silently) 
    389     return EmailMessage(subject, message, from_email, recipient_list, 
    390                         connection=connection).send() 
    391  
    392 def send_mass_mail(datatuple, fail_silently=False, auth_user=None, 
    393                    auth_password=None): 
    394     """ 
    395     Given a datatuple of (subject, message, from_email, recipient_list), sends 
    396     each message to each recipient list. Returns the number of e-mails sent. 
    397  
    398     If from_email is None, the DEFAULT_FROM_EMAIL setting is used. 
    399     If auth_user and auth_password are set, they're used to log in. 
    400     If auth_user is None, the EMAIL_HOST_USER setting is used. 
    401     If auth_password is None, the EMAIL_HOST_PASSWORD setting is used. 
    402  
    403     Note: The API for this method is frozen. New code wanting to extend the 
    404     functionality should use the EmailMessage class directly. 
    405     """ 
    406     connection = SMTPConnection(username=auth_user, password=auth_password, 
    407                                 fail_silently=fail_silently) 
    408     messages = [EmailMessage(subject, message, sender, recipient) 
    409                 for subject, message, sender, recipient in datatuple] 
    410     return connection.send_messages(messages) 
    411  
    412 def mail_admins(subject, message, fail_silently=False): 
    413     """Sends a message to the admins, as defined by the ADMINS setting.""" 
    414     if not settings.ADMINS: 
    415         return 
    416     EmailMessage(settings.EMAIL_SUBJECT_PREFIX + subject, message, 
    417                  settings.SERVER_EMAIL, [a[1] for a in settings.ADMINS] 
    418                  ).send(fail_silently=fail_silently) 
    419  
    420 def mail_managers(subject, message, fail_silently=False): 
    421     """Sends a message to the managers, as defined by the MANAGERS setting.""" 
    422     if not settings.MANAGERS: 
    423         return 
    424     EmailMessage(settings.EMAIL_SUBJECT_PREFIX + subject, message, 
    425                  settings.SERVER_EMAIL, [a[1] for a in settings.MANAGERS] 
    426                  ).send(fail_silently=fail_silently) 

  • /dev/null

    old new  
     1""" 
     2Tools for sending email. 
     3""" 
     4 
     5from django.conf import settings 
     6from django.core.exceptions import ImproperlyConfigured 
     7from django.core.mail.message import EmailMessage, EmailMultiAlternatives 
     8from django.utils.importlib import import_module 
     9 
     10# Imported for backwards compatibility 
     11from django.core.mail.backends.smtp import EmailBackend as _SMTPConnection 
     12 
     13 
     14# Shortcuts for builtin email backends. If settings.EMAIL_BACKEND isn't in 
     15# this list it's treated as a Python import path. 
     16BACKENDS = ('smtp', 'dummy', 'console', 'locmem', 'file') 
     17 
     18 
     19def get_connection(fail_silently=False, **kwds): 
     20    """Load configured email backend and return an instance of it. 
     21 
     22    Both fail_silently and other keyword arguments are used in the 
     23    constructor of the backend. 
     24    """ 
     25    path = settings.EMAIL_BACKEND 
     26    if path in BACKENDS: 
     27        path = 'django.core.mail.backends.%s' % path 
     28    try: 
     29        mod = import_module(path) 
     30    except ImportError, e: 
     31        raise ImproperlyConfigured(('Error importing email backend %s: "%s"' 
     32                                    % (path, e))) 
     33    try: 
     34        cls = getattr(mod, 'EmailBackend') 
     35    except AttributeError: 
     36        raise ImproperlyConfigured(('Module "%s" does not define a ' 
     37                                    '"EmailBackend" class' % path)) 
     38    return cls(fail_silently=fail_silently, **kwds) 
     39 
     40 
     41def send_mail(subject, message, from_email, recipient_list, 
     42              fail_silently=False, auth_user=None, auth_password=None): 
     43    """ 
     44    Easy wrapper for sending a single message to a recipient list. All members 
     45    of the recipient list will see the other recipients in the 'To' field. 
     46 
     47    If auth_user is None, the EMAIL_HOST_USER setting is used. 
     48    If auth_password is None, the EMAIL_HOST_PASSWORD setting is used. 
     49 
     50    Note: The API for this method is frozen. New code wanting to extend the 
     51    functionality should use the EmailMessage class directly. 
     52    """ 
     53    connection = get_connection(username=auth_user, password=auth_password, 
     54                                fail_silently=fail_silently) 
     55    return EmailMessage(subject, message, from_email, recipient_list, 
     56                        connection=connection).send() 
     57 
     58 
     59def send_mass_mail(datatuple, fail_silently=False, auth_user=None, 
     60                   auth_password=None): 
     61    """ 
     62    Given a datatuple of (subject, message, from_email, recipient_list), sends 
     63    each message to each recipient list. Returns the number of e-mails sent. 
     64 
     65    If from_email is None, the DEFAULT_FROM_EMAIL setting is used. 
     66    If auth_user and auth_password are set, they're used to log in. 
     67    If auth_user is None, the EMAIL_HOST_USER setting is used. 
     68    If auth_password is None, the EMAIL_HOST_PASSWORD setting is used. 
     69 
     70    Note: The API for this method is frozen. New code wanting to extend the 
     71    functionality should use the EmailMessage class directly. 
     72    """ 
     73    connection = get_connection(username=auth_user, password=auth_password, 
     74                                fail_silently=fail_silently) 
     75    messages = [EmailMessage(subject, message, sender, recipient) 
     76                for subject, message, sender, recipient in datatuple] 
     77    return connection.send_messages(messages) 
     78 
     79 
     80def mail_admins(subject, message, fail_silently=False): 
     81    """Sends a message to the admins, as defined by the ADMINS setting.""" 
     82    if not settings.ADMINS: 
     83        return 
     84    EmailMessage(settings.EMAIL_SUBJECT_PREFIX + subject, message, 
     85                 settings.SERVER_EMAIL, [a[1] for a in settings.ADMINS] 
     86                 ).send(fail_silently=fail_silently) 
     87 
     88 
     89def mail_managers(subject, message, fail_silently=False): 
     90    """Sends a message to the managers, as defined by the MANAGERS setting.""" 
     91    if not settings.MANAGERS: 
     92        return 
     93    EmailMessage(settings.EMAIL_SUBJECT_PREFIX + subject, message, 
     94                 settings.SERVER_EMAIL, [a[1] for a in settings.MANAGERS] 
     95                 ).send(fail_silently=fail_silently) 
     96 
     97 
     98class SMTPConnection(_SMTPConnection): 
     99 
     100    def __init__(self, *args, **kwds): 
     101        import warnings 
     102        warnings.warn( 
     103            'mail.SMTPConnection is deprectated; use mail.get_connection() instead.', 
     104            DeprecationWarning 
     105        ) 
     106        super(SMTPConnection, self).__init__(*args, **kwds) 

  • /dev/null

    old new  
     1# Mail backends shipped with Django. 

  • /dev/null

    old new  
     1"""Base email backend class.""" 
     2 
     3 
     4class BaseEmailBackend(object): 
     5    """ 
     6    Base class for email backend implementations. 
     7 
     8    Subclasses must at least overwrite send_messages(). 
     9    """ 
     10 
     11    def __init__(self, fail_silently=False, **kwds): 
     12        self.fail_silently = fail_silently 
     13 
     14    def open(self): 
     15        """Open a network connection. 
     16 
     17        This method can be overwritten by backend implementations to 
     18        open a network connection. 
     19 
     20        It's up to the backend implementation to track the status of 
     21        a network connection if it's needed by the backend. 
     22 
     23        This method can be called by applications to force a single 
     24        network connection to be used when sending mails. See the 
     25        send_messages() method of the SMTP backend for a reference 
     26        implementation. 
     27 
     28        The default implementation does nothing. 
     29        """ 
     30        pass 
     31 
     32    def close(self): 
     33        """Close a network connection.""" 
     34        pass 
     35 
     36    def send_messages(self, email_messages): 
     37        """ 
     38        Sends one or more EmailMessage objects and returns the number of email 
     39        messages sent. 
     40        """ 
     41        raise NotImplementedError 

  • /dev/null

    old new  
     1""" 
     2Email backend that writes messages to console instead of sending them. 
     3""" 
     4 
     5import sys 
     6 
     7from django.core.mail.backends.base import BaseEmailBackend 
     8 
     9 
     10class EmailBackend(BaseEmailBackend): 
     11 
     12    def send_messages(self, email_messages): 
     13        for message in email_messages: 
     14            sys.stdout.write('%s\n' % message.message().as_string()) 
     15        return len(email_messages) 

  • /dev/null

    old new  
     1""" 
     2Dummy email backend that does nothing. 
     3""" 
     4 
     5 
     6from django.core.mail.backends.base import BaseEmailBackend 
     7 
     8 
     9class EmailBackend(BaseEmailBackend): 
     10 
     11    def send_messages(self, email_messages): 
     12        return len(email_messages) 

  • /dev/null

    old new  
     1"""Email backend that writes messages to a file.""" 
     2 
     3import os 
     4import sys 
     5import thread 
     6import threading 
     7import time 
     8 
     9try: 
     10    from hashlib import md5 
     11except ImportError: 
     12    from md5 import md5 
     13 
     14from django.conf import settings 
     15from django.core.exceptions import ImproperlyConfigured 
     16from django.core.mail.backends.base import BaseEmailBackend 
     17 
     18 
     19class EmailBackend(BaseEmailBackend): 
     20 
     21    def __init__(self, *args, **kwds): 
     22        self.stream = None 
     23        self._lock = threading.RLock() 
     24        self._counter = 0 
     25        if 'file_path' in kwds: 
     26            self.outdir = kwds.pop('file_path') 
     27        else: 
     28            self.outdir = settings.EMAIL_FILE_PATH 
     29        # Make sure self.outdir is a string. 
     30        if not isinstance(self.outdir, basestring): 
     31            raise ImproperlyConfigured('Path for saving emails is invalid: %r' % self.outdir) 
     32        self.outdir = os.path.abspath(self.outdir) 
     33        # Make sure that self.outdir is an directory if it exists. 
     34        if os.path.exists(self.outdir) and not os.path.isdir(self.outdir): 
     35            raise ImproperlyConfigured('Path for saving email messages exists, but is not a directory: %s' % self.outdir) 
     36        # Try to create it, if it not exists. 
     37        elif not os.path.exists(self.outdir): 
     38            try: 
     39                os.makedirs(self.outdir) 
     40            except OSError, err: 
     41                raise ImproperlyConfigured('Could not create directory for saving email messages: %s (%s)' % (self.outdir, err)) 
     42        # Make sure that self.outdir is writable. 
     43        if not os.access(self.outdir, os.W_OK): 
     44            raise ImproperlyConfigured('Could not write to directory: %s' % self.outdir) 
     45        # Finally, call super(). 
     46        super(EmailBackend, self).__init__(*args, **kwds) 
     47 
     48    def _count(self): 
     49        # counter is required to build a unique filename if connections 
     50        # are opened in a really short time. 
     51        if self._counter == sys.maxint-1: 
     52            self._counter = 0 
     53        self._counter += 1 
     54        return self._counter 
     55 
     56    def _get_filename(self): 
     57        """Return a unique file name.""" 
     58        digest = md5('%d%d%s%d' % (id(self), thread.get_ident(), 
     59                                   time.time(), self._count()) 
     60                     ).hexdigest() 
     61        return os.path.join(self.outdir, '%s-messages.log' % digest) 
     62 
     63    def open(self): 
     64        if self.stream is None: 
     65            self.stream = open(self._get_filename(), 'a') 
     66            return True 
     67        return False 
     68 
     69    def close(self): 
     70        try: 
     71            if self.stream is not None: 
     72                self.stream.close() 
     73        finally: 
     74            self.stream = None 
     75 
     76    def send_messages(self, email_messages): 
     77        """Write all messages to the file in a thread-safe way.""" 
     78        if not email_messages: 
     79            return 
     80        self._lock.acquire() 
     81        try: 
     82            stream_created = self.open() 
     83            for message in email_messages: 
     84                self.stream.write('%s\n' % message.message().as_string()) 
     85                self.stream.write('-'*79) 
     86                self.stream.write('\n') 
     87                self.stream.flush()  # flush after each message 
     88            if stream_created: 
     89                self.close() 
     90        except: 
     91            if not self.fail_silently: 
     92                raise 
     93        finally: 
     94            self._lock.release() 
     95        return len(email_messages) 

  • /dev/null

    old new  
     1""" 
     2Backend for test environment. 
     3""" 
     4 
     5from django.core import mail 
     6from django.core.mail.backends.base import BaseEmailBackend 
     7 
     8 
     9class EmailBackend(BaseEmailBackend): 
     10    """A email backend for use during test sessions. 
     11 
     12    The test connection stores email messages in a dummy outbox, 
     13    rather than sending them out on the wire. 
     14 
     15    The dummy outbox is accessible through the outbox instance attribute. 
     16    """ 
     17 
     18    def __init__(self, *args, **kwds): 
     19        super(EmailBackend, self).__init__(*args, **kwds) 
     20        self.outbox = [] 
     21 
     22    def send_messages(self, messages): 
     23        """Redirect messages to the dummy outbox""" 
     24        self.outbox.extend(messages) 
     25        if hasattr(mail, 'outbox'): 
     26            mail.outbox.extend(messages) 
     27        return len(messages) 

  • /dev/null

    old new  
     1"""SMTP email backend class.""" 
     2 
     3import smtplib 
     4import socket 
     5import threading 
     6 
     7from django.conf import settings 
     8from django.core.mail.backends.base import BaseEmailBackend 
     9from django.core.mail.utils import DNS_NAME 
     10 
     11 
     12class EmailBackend(BaseEmailBackend): 
     13    """ 
     14    A wrapper that manages the SMTP network connection. 
     15    """ 
     16 
     17    def __init__(self, host=None, port=None, username=None, password=None, 
     18                 use_tls=None, fail_silently=False, **kwds): 
     19        super(EmailBackend, self).__init__(fail_silently=fail_silently) 
     20        self.host = host or settings.EMAIL_HOST 
     21        self.port = port or settings.EMAIL_PORT 
     22        self.username = username or settings.EMAIL_HOST_USER 
     23        self.password = password or settings.EMAIL_HOST_PASSWORD 
     24        self.use_tls = (use_tls is not None) and use_tls or settings.EMAIL_USE_TLS 
     25        self.connection = None 
     26        self._lock = threading.RLock() 
     27 
     28    def open(self): 
     29        """ 
     30        Ensures we have a connection to the email server. Returns whether or 
     31        not a new connection was required (True or False). 
     32        """ 
     33        if self.connection: 
     34            # Nothing to do if the connection is already open. 
     35            return False 
     36        try: 
     37            # If local_hostname is not specified, socket.getfqdn() gets used. 
     38            # For performance, we use the cached FQDN for local_hostname. 
     39            self.connection = smtplib.SMTP(self.host, self.port, 
     40                                           local_hostname=DNS_NAME.get_fqdn()) 
     41            if self.use_tls: 
     42                self.connection.ehlo() 
     43                self.connection.starttls() 
     44                self.connection.ehlo() 
     45            if self.username and self.password: 
     46                self.connection.login(self.username, self.password) 
     47            return True 
     48        except: 
     49            if not self.fail_silently: 
     50                raise 
     51 
     52    def close(self): 
     53        """Closes the connection to the email server.""" 
     54        try: 
     55            try: 
     56                self.connection.quit() 
     57            except socket.sslerror: 
     58                # This happens when calling quit() on a TLS connection 
     59                # sometimes. 
     60                self.connection.close() 
     61            except: 
     62                if self.fail_silently: 
     63                    return 
     64                raise 
     65        finally: 
     66            self.connection = None 
     67 
     68    def send_messages(self, email_messages): 
     69        """ 
     70        Sends one or more EmailMessage objects and returns the number of email 
     71        messages sent. 
     72        """ 
     73        if not email_messages: 
     74            return 
     75        self._lock.acquire() 
     76        try: 
     77            new_conn_created = self.open() 
     78            if not self.connection: 
     79                # We failed silently on open(). 
     80                # Trying to send would be pointless. 
     81                return 
     82            num_sent = 0 
     83            for message in email_messages: 
     84                sent = self._send(message) 
     85                if sent: 
     86                    num_sent += 1 
     87            if new_conn_created: 
     88                self.close() 
     89        finally: 
     90            self._lock.release() 
     91        return num_sent 
     92 
     93    def _send(self, email_message): 
     94        """A helper method that does the actual sending.""" 
     95        if not email_message.recipients(): 
     96            return False 
     97        try: 
     98            self.connection.sendmail(email_message.from_email, 
     99                    email_message.recipients(), 
     100                    email_message.message().as_string()) 
     101        except: 
     102            if not self.fail_silently: 
     103                raise 
     104            return False 
     105        return True 

  • /dev/null

    old new  
     1import mimetypes 
     2import os 
     3import random 
     4import time 
     5from email import Charset, Encoders 
     6from email.MIMEText import MIMEText 
     7from email.MIMEMultipart import MIMEMultipart 
     8from email.MIMEBase import MIMEBase 
     9from email.Header import Header 
     10from email.Utils import formatdate, parseaddr, formataddr 
     11 
     12from django.conf import settings 
     13from django.core.mail.utils import DNS_NAME 
     14from django.utils.encoding import smart_str, force_unicode 
     15 
     16# Don't BASE64-encode UTF-8 messages so that we avoid unwanted attention from 
     17# some spam filters. 
     18Charset.add_charset('utf-8', Charset.SHORTEST, Charset.QP, 'utf-8') 
     19 
     20# Default MIME type to use on attachments (if it is not explicitly given 
     21# and cannot be guessed). 
     22DEFAULT_ATTACHMENT_MIME_TYPE = 'application/octet-stream' 
     23 
     24 
     25class BadHeaderError(ValueError): 
     26    pass 
     27 
     28 
     29# Copied from Python standard library, with the following modifications: 
     30# * Used cached hostname for performance. 
     31# * Added try/except to support lack of getpid() in Jython (#5496). 
     32def make_msgid(idstring=None): 
     33    """Returns a string suitable for RFC 2822 compliant Message-ID, e.g: 
     34 
     35    <20020201195627.33539.96671@nightshade.la.mastaler.com> 
     36 
     37    Optional idstring if given is a string used to strengthen the 
     38    uniqueness of the message id. 
     39    """ 
     40    timeval = time.time() 
     41    utcdate = time.strftime('%Y%m%d%H%M%S', time.gmtime(timeval)) 
     42    try: 
     43        pid = os.getpid() 
     44    except AttributeError: 
     45        # No getpid() in Jython, for example. 
     46        pid = 1 
     47    randint = random.randrange(100000) 
     48    if idstring is None: 
     49        idstring = '' 
     50    else: 
     51        idstring = '.' + idstring 
     52    idhost = DNS_NAME 
     53    msgid = '<%s.%s.%s%s@%s>' % (utcdate, pid, randint, idstring, idhost) 
     54    return msgid 
     55 
     56 
     57def forbid_multi_line_headers(name, val): 
     58    """Forbids multi-line headers, to prevent header injection.""" 
     59    val = force_unicode(val) 
     60    if '\n' in val or '\r' in val: 
     61        raise BadHeaderError("Header values can't contain newlines (got %r for header %r)" % (val, name)) 
     62    try: 
     63        val = val.encode('ascii') 
     64    except UnicodeEncodeError: 
     65        if name.lower() in ('to', 'from', 'cc'): 
     66            result = [] 
     67            for item in val.split(', '): 
     68                nm, addr = parseaddr(item) 
     69                nm = str(Header(nm, settings.DEFAULT_CHARSET)) 
     70                result.append(formataddr((nm, str(addr)))) 
     71            val = ', '.join(result) 
     72        else: 
     73            val = Header(val, settings.DEFAULT_CHARSET) 
     74    else: 
     75        if name.lower() == 'subject': 
     76            val = Header(val) 
     77    return name, val 
     78 
     79 
     80class SafeMIMEText(MIMEText): 
     81    def __setitem__(self, name, val): 
     82        name, val = forbid_multi_line_headers(name, val) 
     83        MIMEText.__setitem__(self, name, val) 
     84 
     85 
     86class SafeMIMEMultipart(MIMEMultipart): 
     87    def __setitem__(self, name, val): 
     88        name, val = forbid_multi_line_headers(name, val) 
     89        MIMEMultipart.__setitem__(self, name, val) 
     90 
     91 
     92class EmailMessage(object): 
     93    """ 
     94    A container for email information. 
     95    """ 
     96    content_subtype = 'plain' 
     97    mixed_subtype = 'mixed' 
     98    encoding = None     # None => use settings default 
     99 
     100    def __init__(self, subject='', body='', from_email=None, to=None, bcc=None, 
     101                 connection=None, attachments=None, headers=None): 
     102        """ 
     103        Initialize a single email message (which can be sent to multiple 
     104        recipients). 
     105 
     106        All strings used to create the message can be unicode strings 
     107        (or UTF-8 bytestrings). The SafeMIMEText class will handle any 
     108        necessary encoding conversions. 
     109        """ 
     110        if to: 
     111            assert not isinstance(to, basestring), '"to" argument must be a list or tuple' 
     112            self.to = list(to) 
     113        else: 
     114            self.to = [] 
     115        if bcc: 
     116            assert not isinstance(bcc, basestring), '"bcc" argument must be a list or tuple' 
     117            self.bcc = list(bcc) 
     118        else: 
     119            self.bcc = [] 
     120        self.from_email = from_email or settings.DEFAULT_FROM_EMAIL 
     121        self.subject = subject 
     122        self.body = body 
     123        self.attachments = attachments or [] 
     124        self.extra_headers = headers or {} 
     125        self.connection = connection 
     126 
     127    def get_connection(self, fail_silently=False): 
     128        from django.core.mail import get_connection 
     129        if not self.connection: 
     130            self.connection = get_connection(fail_silently=fail_silently) 
     131        return self.connection 
     132 
     133    def message(self): 
     134        encoding = self.encoding or settings.DEFAULT_CHARSET 
     135        msg = SafeMIMEText(smart_str(self.body, settings.DEFAULT_CHARSET), 
     136                           self.content_subtype, encoding) 
     137        msg = self._create_message(msg) 
     138        msg['Subject'] = self.subject 
     139        msg['From'] = self.extra_headers.pop('From', self.from_email) 
     140        msg['To'] = ', '.join(self.to) 
     141 
     142        # Email header names are case-insensitive (RFC 2045), so we have to 
     143        # accommodate that when doing comparisons. 
     144        header_names = [key.lower() for key in self.extra_headers] 
     145        if 'date' not in header_names: 
     146            msg['Date'] = formatdate() 
     147        if 'message-id' not in header_names: 
     148            msg['Message-ID'] = make_msgid() 
     149        for name, value in self.extra_headers.items(): 
     150            msg[name] = value 
     151        return msg 
     152 
     153    def recipients(self): 
     154        """ 
     155        Returns a list of all recipients of the email (includes direct 
     156        addressees as well as Bcc entries). 
     157        """ 
     158        return self.to + self.bcc 
     159 
     160    def send(self, fail_silently=False): 
     161        """Sends the email message.""" 
     162        if not self.recipients(): 
     163            # Don't bother creating the network connection if there's nobody to 
     164            # send to. 
     165            return 0 
     166        return self.get_connection(fail_silently).send_messages([self]) 
     167 
     168    def attach(self, filename=None, content=None, mimetype=None): 
     169        """ 
     170        Attaches a file with the given filename and content. The filename can 
     171        be omitted and the mimetype is guessed, if not provided. 
     172 
     173        If the first parameter is a MIMEBase subclass it is inserted directly 
     174        into the resulting message attachments. 
     175        """ 
     176        if isinstance(filename, MIMEBase): 
     177            assert content == mimetype == None 
     178            self.attachments.append(filename) 
     179        else: 
     180            assert content is not None 
     181            self.attachments.append((filename, content, mimetype)) 
     182 
     183    def attach_file(self, path, mimetype=None): 
     184        """Attaches a file from the filesystem.""" 
     185        filename = os.path.basename(path) 
     186        content = open(path, 'rb').read() 
     187        self.attach(filename, content, mimetype) 
     188 
     189    def _create_message(self, msg): 
     190        return self._create_attachments(msg) 
     191 
     192    def _create_attachments(self, msg): 
     193        if self.attachments: 
     194            body_msg = msg 
     195            msg = SafeMIMEMultipart(_subtype=self.mixed_subtype) 
     196            if self.body: 
     197                msg.attach(body_msg) 
     198            for attachment in self.attachments: 
     199                if isinstance(attachment, MIMEBase): 
     200                    msg.attach(attachment) 
     201                else: 
     202                    msg.attach(self._create_attachment(*attachment)) 
     203        return msg 
     204 
     205    def _create_mime_attachment(self, content, mimetype): 
     206        """ 
     207        Converts the content, mimetype pair into a MIME attachment object. 
     208        """ 
     209        basetype, subtype = mimetype.split('/', 1) 
     210        if basetype == 'text': 
     211            attachment = SafeMIMEText(smart_str(content, 
     212                settings.DEFAULT_CHARSET), subtype, settings.DEFAULT_CHARSET) 
     213        else: 
     214            # Encode non-text attachments with base64. 
     215            attachment = MIMEBase(basetype, subtype) 
     216            attachment.set_payload(content) 
     217            Encoders.encode_base64(attachment) 
     218        return attachment 
     219 
     220    def _create_attachment(self, filename, content, mimetype=None): 
     221        """ 
     222        Converts the filename, content, mimetype triple into a MIME attachment 
     223        object. 
     224        """ 
     225        if mimetype is None: 
     226            mimetype, _ = mimetypes.guess_type(filename) 
     227            if mimetype is None: 
     228                mimetype = DEFAULT_ATTACHMENT_MIME_TYPE 
     229        attachment = self._create_mime_attachment(content, mimetype) 
     230        if filename: 
     231            attachment.add_header('Content-Disposition', 'attachment', 
     232                                  filename=filename) 
     233        return attachment 
     234 
     235 
     236class EmailMultiAlternatives(EmailMessage): 
     237    """ 
     238    A version of EmailMessage that makes it easy to send multipart/alternative 
     239    messages. For example, including text and HTML versions of the text is 
     240    made easier. 
     241    """ 
     242    alternative_subtype = 'alternative' 
     243 
     244    def __init__(self, subject='', body='', from_email=None, to=None, bcc=None, 
     245            connection=None, attachments=None, headers=None, alternatives=None): 
     246        """ 
     247        Initialize a single email message (which can be sent to multiple 
     248        recipients). 
     249 
     250        All strings used to create the message can be unicode strings (or UTF-8 
     251        bytestrings). The SafeMIMEText class will handle any necessary encoding 
     252        conversions. 
     253        """ 
     254        super(EmailMultiAlternatives, self).__init__(subject, body, from_email, to, bcc, connection, attachments, headers) 
     255        self.alternatives=alternatives or [] 
     256 
     257    def attach_alternative(self, content, mimetype): 
     258        """Attach an alternative content representation.""" 
     259        assert content is not None 
     260        assert mimetype is not None 
     261        self.alternatives.append((content, mimetype)) 
     262 
     263    def _create_message(self, msg): 
     264        return self._create_attachments(self._create_alternatives(msg)) 
     265 
     266    def _create_alternatives(self, msg): 
     267        if self.alternatives: 
     268            body_msg = msg 
     269            msg = SafeMIMEMultipart(_subtype=self.alternative_subtype) 
     270            if self.body: 
     271                msg.attach(body_msg) 
     272            for alternative in self.alternatives: 
     273                msg.attach(self._create_mime_attachment(*alternative)) 
     274        return msg 

  • /dev/null

    old new  
     1""" 
     2Email message and email sending related helper functions. 
     3""" 
     4 
     5import socket 
     6 
     7 
     8# Cache the hostname, but do it lazily: socket.getfqdn() can take a couple of 
     9# seconds, which slows down the restart of the server. 
     10class CachedDnsName(object): 
     11    def __str__(self): 
     12        return self.get_fqdn() 
     13 
     14    def get_fqdn(self): 
     15        if not hasattr(self, '_fqdn'): 
     16            self._fqdn = socket.getfqdn() 
     17        return self._fqdn 
     18 
     19DNS_NAME = CachedDnsName() 

  • a/django/test/utils.py

    old new  
    2828    signals.template_rendered.send(sender=self, template=self, context=context) 
    2929    return self.nodelist.render(context) 
    3030 
    31 class TestSMTPConnection(object): 
    32     """A substitute SMTP connection for use during test sessions. 
    33     The test connection stores email messages in a dummy outbox, 
    34     rather than sending them out on the wire. 
    35  
    36     """ 
    37     def __init__(*args, **kwargs): 
    38         pass 
    39     def open(self): 
    40         "Mock the SMTPConnection open() interface" 
    41         pass 
    42     def close(self): 
    43         "Mock the SMTPConnection close() interface" 
    44         pass 
    45     def send_messages(self, messages): 
    46         "Redirect messages to the dummy outbox" 
    47         mail.outbox.extend(messages) 
    48         return len(messages) 
    4931 
    5032def setup_test_environment(): 
    5133    """Perform any global pre-test setup. This involves: 
    5234 
    5335        - Installing the instrumented test renderer 
    54         - Diverting the email sending functions to a test buffer 
     36        - Replacing the email backend with the email backend used for testing. 
    5537        - Setting the active locale to match the LANGUAGE_CODE setting. 
    5638    """ 
     39    from django.core.mail.backends.locmem import EmailBackend 
    5740    Template.original_render = Template.render 
    5841    Template.render = instrumented_test_render 
    5942 
    60     mail.original_SMTPConnection = mail.SMTPConnection 
    61     mail.SMTPConnection = TestSMTPConnection 
     43    mail.original_email_backend = settings.EMAIL_BACKEND 
     44    settings.EMAIL_BACKEND = 'locmem' 
     45    mail.original_smtp_connection = mail.SMTPConnection 
     46    mail.SMTPConnection = lambda *a, **k: mail.get_connection() 
    6247 
    6348    mail.outbox = [] 
    6449 
    …… 
    7459    Template.render = Template.original_render 
    7560    del Template.original_render 
    7661 
    77     mail.SMTPConnection = mail.original_SMTPConnection 
    78     del mail.original_SMTPConnection 
     62    settings.EMAIL_BACKEND = mail.original_email_backend 
     63    del mail.original_email_backend 
     64    mail.SMTPConnection = mail.original_smtp_connection 
     65    del mail.original_smtp_connection 
    7966 
    8067    del mail.outbox 
    8168 

  • a/docs/ref/settings.txt

    old new  
    379379This is only used if ``CommonMiddleware`` is installed (see 
    380380:ref:`topics-http-middleware`). 
    381381 
     382.. setting:: EMAIL_BACKEND 
     383 
     384EMAIL_BACKEND 
     385------------- 
     386 
     387.. versionadded:: 1.2 
     388 
     389Default: ``'smtp'`` 
     390 
     391The backend to use for sending emails. For available backend see 
     392:ref:`topics-email`. 
     393 
    382394.. setting:: EMAIL_HOST 
    383395 
    384396EMAIL_HOST 

  • a/docs/topics/email.txt

    old new  
    178178 
    179179.. _emailmessage-and-smtpconnection: 
    180180 
    181 The EmailMessage and SMTPConnection classes 
    182 =========================================== 
     181The EmailMessage class 
     182====================== 
    183183 
    184184.. versionadded:: 1.0 
    185185 
    186186Django's ``send_mail()`` and ``send_mass_mail()`` functions are actually thin 
    187 wrappers that make use of the ``EmailMessage`` and ``SMTPConnection`` classes 
    188 in ``django.core.mail``.  If you ever need to customize the way Django sends 
    189 e-mail, you can subclass these two classes to suit your needs. 
     187wrappers that make use of the ``EmailMessage`` class in ``django.core.mail``. 
     188 
     189Not all features of the ``EmailMessage`` class are available through the 
     190``send_mail()`` and related wrapper functions. If you wish to use advanced 
     191features, such as BCC'ed recipients, file attachments, or multi-part 
     192e-mail, you'll need to create ``EmailMessage`` instances directly. 
    190193 
    191194.. note:: 
    192     Not all features of the ``EmailMessage`` class are available through the 
    193     ``send_mail()`` and related wrapper functions. If you wish to use advanced 
    194     features, such as BCC'ed recipients, file attachments, or multi-part 
    195     e-mail, you'll need to create ``EmailMessage`` instances directly. 
    196195 
    197196    This is a design feature. ``send_mail()`` and related functions were 
    198197    originally the only interface Django provided. However, the list of 
    …… 
    201200    original functions only for backwards compatibility. 
    202201 
    203202In general, ``EmailMessage`` is responsible for creating the e-mail message 
    204 itself. ``SMTPConnection`` is responsible for the network connection side of 
    205 the operation. This means you can reuse the same connection (an 
    206 ``SMTPConnection`` instance) for multiple messages. 
     203itself. The email backend is responsible for sending the email. By default 
     204the SMTP backend is used to send emails using a SMTP server. 
     205 
     206If you're sending lots of messages at once, the ``send_messages()`` method of 
     207the email backend is useful. It takes a list of ``EmailMessage`` 
     208instances (or subclasses) and sends them over a single connection. For example, 
     209if you have a function called ``get_notification_email()`` that returns a 
     210list of ``EmailMessage`` objects representing some periodic e-mail you wish to 
     211send out, you could send this with:: 
     212 
     213    connection = SMTPConnection()   # Use default settings for connection 
     214    messages = get_notification_email() 
     215    connection.send_messages(messages) 
     216 
     217If you want to resuse the same connection for multiple messages, but can't 
     218use ``send_messages()``, you'll have to use the ``open()`` and ``close()`` 
     219methods of the email backend:: 
     220 
     221    from django.core import mail 
     222 
     223    connection = mail.get_connection() 
     224    connection.open() 
     225    email1 = mail.EmailMessage('Hello', 'Body goes here', 'from@example.com', 
     226                               ['to1@example.com'], connection=connection) 
     227    email1.send() 
     228    email2 = mail.EmailMessage('Hello again', 'Body goes here', 
     229                               'from@example.com', ['to1@example.com'], 
     230                               connection=connection) 
     231    email2.send() 
     232    connection.close() 
     233 
    207234 
    208235EmailMessage Objects 
    209236-------------------- 
    …… 
    227254    * ``bcc``: A list or tuple of addresses used in the "Bcc" header when 
    228255      sending the e-mail. 
    229256 
    230     * ``connection``: An ``SMTPConnection`` instance. Use this parameter if 
     257    * ``connection``: An email backend instance. Use this parameter if 
    231258      you want to use the same connection for multiple messages. If omitted, a 
    232259      new connection is created when ``send()`` is called. 
    233260 
    …… 
    331358    msg.content_subtype = "html"  # Main content is now text/html 
    332359    msg.send() 
    333360 
    334 SMTPConnection Objects 
    335 ---------------------- 
     361 
     362Email Backends 
     363============== 
     364 
     365.. versionadded:: 1.2 
     366 
     367The actual sending of an email is handled by the email backend. 
     368By default the SMTP backend will be used. 
     369 
     370Your email backend preferences goes in the ``EMAIL_BACKEND`` setting in 
     371your settings file. Here's an explanation of all available values for 
     372``EMAIL_BACKEND``. 
     373 
     374SMTP backend 
     375------------ 
     376 
     377This is the default backend. Email will be sent through a SMTP server. 
     378The server address and authentication credentials are set in the 
     379:setting:`EMAIL_HOST`, :setting:`EMAIL_POST`, :setting:`EMAIL_HOST_USER`, 
     380:setting:`EMAIL_HOST_PASSWORD` and :setting:`EMAIL_USE_TLS` settings in your 
     381settings file. 
     382 
     383The SMTP backend is configured in the default settings:: 
     384 
     385    EMAIL_BACKEND = 'smtp' 
     386 
     387 
     388SMTPConnection objects 
     389~~~~~~~~~~~~~~~~~~~~~~ 
    336390 
    337391.. class:: SMTPConnection 
    338392 
     393.. note:: 
     394 
     395   ``mail.SMTPConnection`` is deprecated, use ``mail.get_connection`` instead. 
     396   For backwards compatibility ``SMTPConnection`` is still available in 
     397   ``django.core.mail`` as an alias for the SMTP backend. 
     398 
    339399The ``SMTPConnection`` class is initialized with the host, port, username and 
    340400password for the SMTP server. If you don't specify one or more of those 
    341401options, they are read from your settings file. 
    342402 
    343 If you're sending lots of messages at once, the ``send_messages()`` method of 
    344 the ``SMTPConnection`` class is useful. It takes a list of ``EmailMessage`` 
    345 instances (or subclasses) and sends them over a single connection. For example, 
    346 if you have a function called ``get_notification_email()`` that returns a 
    347 list of ``EmailMessage`` objects representing some periodic e-mail you wish to 
    348 send out, you could send this with:: 
     403Console backend (for development) 
     404--------------------------------- 
    349405 
    350     connection = SMTPConnection()   # Use default settings for connection 
    351     messages = get_notification_email() 
    352     connection.send_messages(messages) 
     406Instead of sending out real emails the console backend just writes the emails 
     407that would be send to the standard output. To use this backend, use 
     408in your settings:: 
    353409 
    354 Testing e-mail sending 
    355 ---------------------- 
     410    EMAIL_BACKEND = 'console' 
     411 
     412File backend (for development) 
     413------------------------------ 
     414 
     415The file backend writes emails to a file. A new file is created for each 
     416new instance of this backend. The directory to which the files are written 
     417is either taken from the :setting:`EMAIL_FILE_PATH` setting or from the 
     418``file_path`` keyword when creating a connection with ``get_connection()``. 
     419To use this backend, use in your settings:: 
     420 
     421    EMAIL_BACKEND = 'file' 
     422    EMAIL_FILE_PATH = '/tmp/app-messages' # change this to a proper location 
     423 
     424Dummy backend (for development) 
     425------------------------------- 
     426 
     427As the name suggests the dummy backend does nothing with your messages. 
     428To enable this backend, use in your settings file:: 
     429 
     430   EMAIL_BACKEND = 'dummy' 
     431 
     432This backend can be useful during development, if you even want to suppress 
     433the output produced by the console backend. 
     434 
     435Using a custom email backend 
     436---------------------------- 
     437 
     438If you need to change how emails are send you can write your own email 
     439backend. The ``EMAIL_BACKEND`` setting in your settings file is then the 
     440Python import path for your backend. 
     441 
     442Custom email backends should subclass ``BaseEmailBackend`` that is located 
     443in the ``django.core.mail.backends.base`` module. A custom email 
     444backend must implement the ``send_messages(email_messages)`` method. This 
     445method receives a list of ``EMailMessage`` instances and returns the number 
     446of successfully delivered messages. If your backend should be capable of 
     447network connection handling, you should implement both the ``open()`` 
     448and ``close()`` methods too. Refer to ``SMTPEmailBackend`` for a reference 
     449implementation. 
     450 
     451Testing Email Sending 
     452===================== 
    356453 
    357454The are times when you do not want Django to send e-mails at all. For example, 
    358455while developing a website, you probably don't want to send out thousands of 
    …… 
    360457people under the right conditions, and that those e-mails will contain the 
    361458correct content. 
    362459 
    363 The easiest way to test your project's use of e-mail is to use a "dumb" e-mail 
    364 server that receives the e-mails locally and displays them to the terminal, 
    365 but does not actually send anything. Python has a built-in way to accomplish 
    366 this with a single command:: 
     460The easiest way to test your project's use of e-mail is to change the 
     461``EMAIL_BACKEND`` setting in your settings file to ``'console'`` to use 
     462a backend that doesn't send any email but writes them to the 
     463terminal. 
     464 
     465Alternatively use a "dumb" e-mail server that receives the e-mails locally 
     466and displays them to the terminal, but does not actually send anything. 
     467Python has a built-in way to accomplish this with a single command:: 
    367468 
    368469    python -m smtpd -n -c DebuggingServer localhost:1025 
    369470 

  • a/docs/topics/testing.txt

    old new  
    11171117contents of each message -- without actually sending the messages. 
    11181118 
    11191119The test runner accomplishes this by transparently replacing the normal 
    1120 :class:`~django.core.mail.SMTPConnection` class with a different version. 
     1120email backend with a testing backend. 
    11211121(Don't worry -- this has no effect on any other e-mail senders outside of 
    11221122Django, such as your machine's mail server, if you're running one.) 
    11231123 
    …… 
    11291129``django.core.mail.outbox``. This is a simple list of all 
    11301130:class:`<~django.core.mail.EmailMessage>` instances that have been sent. 
    11311131It does not exist under normal execution conditions, i.e., when you're not 
    1132 running unit tests. The outbox is created during test setup, along with the 
    1133 dummy :class:`<~django.core.mail.SMTPConnection>`. When the test framework is 
    1134 torn down, the standard :class:`<~django.core.mail.SMTPConnection>` class is 
     1132running unit tests. The outbox is created during test setup. 
     1133When the test framework is torn down, the standard mail backend 
    11351134restored, and the test outbox is destroyed. 
    11361135 
    11371136The ``outbox`` attribute is a special attribute that is created *only* when 

  • /dev/null

    old new  
     1"""A custom backend for testing.""" 
     2 
     3from django.core.mail.backends.base import BaseEmailBackend 
     4 
     5 
     6class EmailBackend(BaseEmailBackend): 
     7 
     8    def send_messages(self, email_messages): 
     9        return len(email_messages) 

  • a/tests/regressiontests/mail/tests.py

    old new  
    11# coding: utf-8 
     2 
    23r""" 
    34# Tests for the django.core.mail. 
    45 
     6>>> import os 
     7>>> import shutil 
     8>>> import tempfile 
    59>>> from django.conf import settings 
    610>>> from django.core import mail 
    711>>> from django.core.mail import EmailMessage, mail_admins, mail_managers, EmailMultiAlternatives 
     12>>> from django.core.mail.backends.base import BaseEmailBackend 
     13>>> from django.core.mail.backends import console, dummy, locmem, file 
    814>>> from django.utils.translation import ugettext_lazy 
    915 
    1016# Test normal ascii character case: 
    …… 
    138144JVBERi0xLjQuJS4uLg== 
    139145... 
    140146 
     147# Make sure that the console backend writes to stdout 
     148>>> connection = console.EmailBackend() 
     149>>> email = EmailMessage('Subject', 'Content', 'bounce@example.com', ['to@example.com'], headers={'From': 'from@example.com'}) 
     150>>> connection.send_messages([email]) 
     151Content-Type: text/plain; charset="utf-8" 
     152MIME-Version: 1.0 
     153Content-Transfer-Encoding: quoted-printable 
     154Subject: Subject 
     155From: from@example.com 
     156To: to@example.com 
     157Date: ... 
     158Message-ID: ... 
     159 
     160Content 
     161... 
     1621 
     163 
     164# Make sure that dummy backends returns correct number of sent messages 
     165>>> connection = dummy.EmailBackend() 
     166>>> email = EmailMessage('Subject', 'Content', 'bounce@example.com', ['to@example.com'], headers={'From': 'from@example.com'}) 
     167>>> connection.send_messages([email, email, email]) 
     1683 
     169 
     170# Make sure that locmen backend populates the outbox 
     171>>> mail.outbox = [] 
     172>>> connection = locmem.EmailBackend() 
     173>>> email1 = EmailMessage('Subject', 'Content', 'bounce@example.com', ['to@example.com'], headers={'From': 'from@example.com'}) 
     174>>> email2 = EmailMessage('Subject 2', 'Content', 'bounce@example.com', ['to@example.com'], headers={'From': 'from@example.com'}) 
     175>>> connection.send_messages([email1, email2]) 
     1762 
     177>>> len(mail.outbox) 
     1782 
     179>>> mail.outbox[0].subject 
     180'Subject' 
     181>>> mail.outbox[1].subject 
     182'Subject 2' 
     183 
     184# Make sure that multiple locmem connections share mail.outbox 
     185>>> mail.outbox = [] 
     186>>> connection1 = locmem.EmailBackend() 
     187>>> connection2 = locmem.EmailBackend() 
     188>>> email = EmailMessage('Subject', 'Content', 'bounce@example.com', ['to@example.com'], headers={'From': 'from@example.com'}) 
     189>>> connection1.send_messages([email]) 
     1901 
     191>>> connection2.send_messages([email]) 
     1921 
     193>>> len(connection1.outbox) 
     1941 
     195>>> len(connection2.outbox) 
     1961 
     197>>> len(mail.outbox) 
     1982 
     199 
     200# Make sure that the file backend write to the right location 
     201>>> tmp_dir = tempfile.mkdtemp() 
     202>>> shutil.rmtree(tmp_dir) 
     203>>> connection = file.EmailBackend(file_path=tmp_dir) 
     204>>> email = EmailMessage('Subject', 'Content', 'bounce@example.com', ['to@example.com'], headers={'From': 'from@example.com'}) 
     205>>> connection.send_messages([email]) 
     2061 
     207>>> len(os.listdir(tmp_dir)) 
     2081 
     209>>> print open(os.path.join(tmp_dir, os.listdir(tmp_dir)[0])).read() 
     210Content-Type: text/plain; charset="utf-8" 
     211MIME-Version: 1.0 
     212Content-Transfer-Encoding: quoted-printable 
     213Subject: Subject 
     214From: from@example.com 
     215To: to@example.com 
     216Date: ... 
     217Message-ID: ... 
     218 
     219Content 
     220... 
     221>>> connection2 = file.EmailBackend(file_path=tmp_dir) 
     222>>> connection2.send_messages([email]) 
     2231 
     224>>> len(os.listdir(tmp_dir)) 
     2252 
     226>>> connection.send_messages([email]) 
     2271 
     228>>> len(os.listdir(tmp_dir)) 
     2293 
     230>>> email.connection = connection 
     231>>> connection_created = connection.open() 
     232>>> num_sent = email.send() 
     233>>> len(os.listdir(tmp_dir)) 
     2344 
     235>>> num_sent = email.send() 
     236>>> len(os.listdir(tmp_dir)) 
     2374 
     238>>> connection.close() 
     239>>> shutil.rmtree(tmp_dir) 
     240 
     241# Make sure that get_connection() accepts arbitrary keyword that might be 
     242# used with custom backends. 
     243>>> c = mail.get_connection(fail_silently=True, foo='bar') 
     244>>> c.fail_silently 
     245True 
     246 
     247# Test custom backend defined in this suite. 
     248>>> settings.EMAIL_BACKEND = 'regressiontests.mail.custombackend' 
     249>>> conn = mail.get_connection() 
     250>>> email = EmailMessage('Subject', 'Content', 'bounce@example.com', ['to@example.com'], headers={'From': 'from@example.com'}) 
     251>>> conn.send_messages([email]) 
     2521 
     253>>> settings.EMAIL_BACKEND = 'locmem' 
    141254"""