Corrected spelling of e-mail (according to our standard).

CSRF', where an attacking site tricks a user's browser into logging

into a site with someone else's credentials, is also covered.

Email Backends

--------------

E-mail Backends

---------------

You can now :ref:`configure the way that Django sends email

<topic-email-backends>`. Instead of using SMTP to send all email, you

can now choose a configurable email backend to send messages. If your

You can now :ref:`configure the way that Django sends e-mail

<topic-email-backends>`. Instead of using SMTP to send all e-mail, you

can now choose a configurable e-mail backend to send messages. If your

hosting provider uses a sandbox or some other non-SMTP technique for

sending mail, you can now construct an email backend that will allow

sending mail, you can now construct an e-mail backend that will allow

Django's standard :ref:`mail sending methods<topics-email>` to use

those facilities.

This also makes it easier to debug mail sending - Django ships with

backend implementations that allow you to send email to a

backend implementations that allow you to send e-mail to a

:ref:`file<topic-email-file-backend>`, to the

:ref:`console<topic-email-console-backend>`, or to

:ref:`memory<topic-email-memory-backend>` - you can even configure all

email to be :ref:`thrown away<topic-email-console-backend>`.

e-mail to be :ref:`thrown away<topic-email-dummy-backend>`.

Although Python makes sending e-mail relatively easy via the `smtplib

library`_, Django provides a couple of light wrappers over it. These wrappers

are provided to make sending e-mail extra quick, to make it easy to test

email sending during development, and to provide support for platforms that

e-mail sending during development, and to provide support for platforms that

can't use SMTP.

The code lives in the ``django.core.mail`` module.

    * ``auth_password``: The optional password to use to authenticate to the

      SMTP server. If this isn't provided, Django will use the value of the

      ``EMAIL_HOST_PASSWORD`` setting.

    * ``connection``: The optional email backend to use to send the mail.

    * ``connection``: The optional e-mail backend to use to send the mail.

      If unspecified, an instance of the default backend will be used.

      See the documentation on :ref:`E-mail backends <topic-email-backends>`

      for more details.

responsible for sending the e-mail.

For convenience, :class:`~django.core.mail.EmailMessage` provides a simple

``send()`` method for sending a single email. If you need to send multiple

messages, the email backend API :ref:`provides an alternative

``send()`` method for sending a single e-mail. If you need to send multiple

messages, the e-mail backend API :ref:`provides an alternative

<topics-sending-multiple-emails>`.

EmailMessage Objects

The class has the following methods:

    * ``send(fail_silently=False)`` sends the message. If a connection was

      specified when the email was constructed, that connection will be used.

      specified when the e-mail was constructed, that connection will be used.

      Otherwise, an instance of the default backend will be instantiated and

      used. If the keyword argument ``fail_silently`` is ``True``, exceptions

      raised while sending the message will be quashed.

The e-mail backend class has the following methods:

    * ``open()`` instantiates an long-lived email-sending connection.

    * ``open()`` instantiates an long-lived e-mail-sending connection.

    * ``close()`` closes the current email-sending connection.

    * ``close()`` closes the current e-mail-sending connection.

    * ``send_messages(email_messages)`` sends a list of

      :class:`~django.core.mail.EmailMessage` objects. If the connection is

.. function:: get_connection(backend=None, fail_silently=False, *args, **kwargs)

By default, a call to ``get_connection()`` will return an instance of the

email backend specified in :setting:`EMAIL_BACKEND`. If you specify the

e-mail backend specified in :setting:`EMAIL_BACKEND`. If you specify the

``backend`` argument, an instance of that backend will be instantiated.

The ``fail_silently`` argument controls how the backend should handle errors.

If ``fail_silently`` is True, exceptions during the email sending process

If ``fail_silently`` is True, exceptions during the e-mail sending process

will be silently ignored.

All other arguments are passed directly to the constructor of the

Django ships with several e-mail sending backends. With the exception of the

SMTP backend (which is the default), these backends are only useful during

testing and development. If you have special email sending requirements, you

can :ref:`write your own email backend <topic-custom-email-backend>`.

testing and development. If you have special e-mail sending requirements, you

can :ref:`write your own e-mail backend <topic-custom-email-backend>`.

.. _topic-email-smtp-backend:

    Prior to version 1.2, Django provided a

    :class:`~django.core.mail.SMTPConnection` class. This class provided a way

    to directly control the use of SMTP to send email. This class has been

    deprecated in favor of the generic email backend API.

    to directly control the use of SMTP to send e-mail. This class has been

    deprecated in favor of the generic e-mail backend API.

    For backwards compatibility :class:`~django.core.mail.SMTPConnection` is

    still available in ``django.core.mail`` as an alias for the SMTP backend.

.. _topics-sending-multiple-emails:

Sending multiple emails

-----------------------

Sending multiple e-mails

------------------------

Establishing and closing an SMTP connection (or any other network connection,

for that matter) is an expensive process. If you have a lot of emails to send,

for that matter) is an expensive process. If you have a lot of e-mails to send,

it makes sense to reuse an SMTP connection, rather than creating and

destroying a connection every time you want to send an email.

destroying a connection every time you want to send an e-mail.

There are two ways you tell an email backend to reuse a connection.

There are two ways you tell an e-mail backend to reuse a connection.

Firstly, you can use the ``send_messages()`` method. ``send_messages()`` takes

a list of :class:`~django.core.mail.EmailMessage` instances (or subclasses),

For example, if you have a function called ``get_notification_email()`` that

returns a list of :class:`~django.core.mail.EmailMessage` objects representing

some periodic e-mail you wish to send out, you could send these emails using

some periodic e-mail you wish to send out, you could send these e-mails using

a single call to send_messages::

    from django.core import mail

    connection = mail.get_connection()   # Use default email connection

    connection = mail.get_connection()   # Use default e-mail connection

    messages = get_notification_email()

    connection.send_messages(messages)

backend, sends the list of messages, and then closes the connection again.

The second approach is to use the ``open()`` and ``close()`` methods on the

email backend to manually control the connection. ``send_messages()`` will not

e-mail backend to manually control the connection. ``send_messages()`` will not

manually open or close the connection if it is already open, so if you

manually open the connection, you can control when it is closed. For example::

    # Manually open the connection

    connection.open()

    # Construct an email message that uses the connection

    # Construct an e-mail message that uses the connection

    email1 = mail.EmailMessage('Hello', 'Body goes here', 'from@example.com',

                              ['to1@example.com'], connection=connection)

    email1.send() # Send the email

    email1.send() # Send the e-mail

    # Construct two more messages

    email2 = mail.EmailMessage('Hello', 'Body goes here', 'from@example.com',

    email3 = mail.EmailMessage('Hello', 'Body goes here', 'from@example.com',

                              ['to3@example.com'])

    # Send the two emails in a single call -

    # Send the two e-mails in a single call -

    connection.send_messages([email2, email3])

    # The connection was already open so send_messages() doesn't close it.

    # We need to manually close the connection.

correct content.

The easiest way to test your project's use of e-mail is to use the ``console``

email backend. This backend redirects all email to stdout, allowing you to

e-mail backend. This backend redirects all e-mail to stdout, allowing you to

inspect the content of mail.

The ``file`` email backend can also be useful during development -- this backend

The ``file`` e-mail backend can also be useful during development -- this backend

dumps the contents of every SMTP connection to a file that can be inspected

at your leisure.

.. deprecated:: 1.2

The ``SMTPConnection`` class has been deprecated in favor of the generic email

The ``SMTPConnection`` class has been deprecated in favor of the generic e-mail

backend API.

For backwards compatibility ``SMTPConnection`` is still available in