Django

Code

Changeset 5155

Show
Ignore:
Timestamp:
05/05/07 23:23:12 (1 year ago)
Author:
adrian
Message:

Edited docs/email.txt changes from [5141] and other recent changesets

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • django/trunk/docs/email.txt

    r5147 r5155  
    2121        ['to@example.com'], fail_silently=False) 
    2222 
    23 Mail will be sent using the SMTP host and port specified in the `EMAIL_HOST`_ 
    24 and `EMAIL_PORT`_ settings. The `EMAIL_HOST_USER`_ and `EMAIL_HOST_PASSWORD`_ 
    25 settings, if set, will be used to authenticate to the SMTP server and the 
    26 `EMAIL_USE_TLS`_ settings will control whether a secure connection is used. 
     23Mail is sent using the SMTP host and port specified in the `EMAIL_HOST`_ and 
     24`EMAIL_PORT`_ settings. The `EMAIL_HOST_USER`_ and `EMAIL_HOST_PASSWORD`_ 
     25settings, if set, are used to authenticate to the SMTP server, and the 
     26`EMAIL_USE_TLS`_ setting controls whether a secure connection is used. 
    2727 
    2828.. note:: 
    2929 
    30     The character set of email sent with ``django.core.mail`` will be set to 
     30    The character set of e-mail sent with ``django.core.mail`` will be set to 
    3131    the value of your `DEFAULT_CHARSET setting`_. 
    3232 
    …… 
    3737.. _EMAIL_HOST_PASSWORD: ../settings/#email-host-password 
    3838.. _EMAIL_USE_TLS: ../settings/#email-use-tls 
    39  
    4039 
    4140send_mail() 
    …… 
    194193Django's ``send_mail()`` and ``send_mass_mail()`` functions are actually thin 
    195194wrappers that make use of the ``EmailMessage`` and ``SMTPConnection`` classes 
    196 in ``django.mail``.  If you ever need to customize the way Django sends email, 
    197 you can subclass these two classes to suit your needs. 
     195in ``django.core.mail``.  If you ever need to customize the way Django sends 
     196e-mail, you can subclass these two classes to suit your needs. 
    198197 
    199198.. note:: 
    200199    Not all features of the ``EmailMessage`` class are available through the 
    201200    ``send_mail()`` and related wrapper functions. If you wish to use advanced 
    202     features such as including BCC recipients or multi-part email, you will 
    203     need to create ``EmailMessage`` instances directly. 
    204  
    205 In general, ``EmailMessage`` is responsible for creating the email message 
     201    features, such as BCC'ed recipients or multi-part e-mail, you'll need to 
     202    create ``EmailMessage`` instances directly. 
     203 
     204In general, ``EmailMessage`` is responsible for creating the e-mail message 
    206205itself. ``SMTPConnection`` is responsible for the network connection side of 
    207206the operation. This means you can reuse the same connection (an 
    208207``SMTPConnection`` instance) for multiple messages. 
    209208 
    210 The ``EmailMessage`` class is initialised as follows:: 
     209The ``EmailMessage`` class is initialized as follows:: 
    211210 
    212211    email = EmailMessage(subject, body, from_email, to, bcc, connection) 
    …… 
    214213All of these parameters are optional. If ``from_email`` is omitted, the value 
    215214from ``settings.DEFAULT_FROM_EMAIL`` is used. Both the ``to`` and ``bcc`` 
    216 parameters are lists of addresses. 
    217  
    218 The class has the following methods that you can use: 
    219  
    220  * ``send()`` sends the message, using either the connection that is specified 
    221    in the ``connection`` attribute, or creating a new connection if none already 
    222    exists. 
    223  * ``message()`` constructs a ``django.core.mail.SafeMIMEText`` object (a 
    224    sub-class of Python's ``email.MIMEText.MIMEText`` class) holding the 
    225    message to be sent. If you ever need to extend the `EmailMessage` class, 
    226    you will probably want to override this method to put the content you wish 
    227    into the MIME object. 
    228  * ``recipients()`` returns a lists of all the recipients of the message, 
    229    whether they are recorded in the ``to`` or ``bcc`` attributes. This is 
    230    another method you need to possibly override when sub-classing, since the 
    231    SMTP server needs to be told the full list of recipients when the message 
    232    is sent. If you add another way to specify recipients in your class, they 
    233    need to be returned from this method as well. 
     215parameters are lists of addresses, as strings. 
     216 
     217For example:: 
     218 
     219    email = EmailMessage('Hello', 'Body goes here', 'from@example.com', 
     220                ['to1@example.com', 'to2@example.com'], 
     221                ['bcc@example.com']) 
     222 
     223The class has the following methods: 
     224 
     225    * ``send()`` sends the message, using either the connection that is 
     226      specified in the ``connection`` attribute, or creating a new connection 
     227      if none already exists. 
     228 
     229    * ``message()`` constructs a ``django.core.mail.SafeMIMEText`` object (a 
     230      sub-class of Python's ``email.MIMEText.MIMEText`` class) holding the 
     231      message to be sent. If you ever need to extend the `EmailMessage` class, 
     232      you'll probably want to override this method to put the content you wish 
     233      into the MIME object. 
     234 
     235    * ``recipients()`` returns a list of all the recipients of the message, 
     236      whether they're recorded in the ``to`` or ``bcc`` attributes. This is 
     237      another method you might need to override when sub-classing, because the 
     238      SMTP server needs to be told the full list of recipients when the message 
     239      is sent. If you add another way to specify recipients in your class, they 
     240      need to be returned from this method as well. 
    234241 
    235242The ``SMTPConnection`` class is initialized with the host, port, username and 
    …… 
    237244options, they are read from your settings file. 
    238245 
    239 If you are sending lots of messages at once, the ``send_messages()`` method of 
    240 the ``SMTPConnection`` class will be useful. It takes a list of ``EmailMessage`` 
    241 instances (or sub-classes) and sends them over a single connection. For 
    242 example, if you have a function called ``get_notification_email()`` that returns a 
    243 list of ``EmailMessage`` objects representing some periodic email you wish to 
     246If you're sending lots of messages at once, the ``send_messages()`` method of 
     247the ``SMTPConnection`` class is useful. It takes a list of ``EmailMessage`` 
     248instances (or subclasses) and sends them over a single connection. For example, 
     249if you have a function called ``get_notification_email()`` that returns a 
     250list of ``EmailMessage`` objects representing some periodic e-mail you wish to 
    244251send out, you could send this with:: 
    245252 
    …… 
    247254    messages = get_notification_email() 
    248255    connection.send_messages(messages) 
    249