==============

Sending e-mail

==============

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

Django provides a couple of light wrappers over it, to make sending e-mail

extra quick.

The code lives in a single module: ``django.core.mail``.

.. _smtplib library: http://www.python.org/doc/current/lib/module-smtplib.html

Quick example

=============

In two lines::

    from django.core.mail import send_mail

    send_mail('Subject here', 'Here is the message.', 'from@example.com',

        ['to@example.com'], fail_silently=False)

.. note::

    The character set of email sent with ``django.core.mail`` will be set to

    the value of your `DEFAULT_CHARSET setting`_.

.. _DEFAULT_CHARSET setting: ../settings/#DEFAULT_CHARSET

send_mail()

===========

The simplest way to send e-mail is using the function

``django.core.mail.send_mail()``. Here's its definition::

    send_mail(subject, message, from_email, recipient_list,

        fail_silently=False, auth_user=None,

        auth_password=None)

The ``subject``, ``message``, ``from_email`` and ``recipient_list`` parameters

are required.

    * ``subject``: A string.

    * ``message``: A string.

    * ``from_email``: A string.

    * ``recipient_list``: A list of strings, each an e-mail address. Each

      member of ``recipient_list`` will see the other recipients in the "To:"

      field of the e-mail message.

    * ``fail_silently``: A boolean. If it's ``False``, ``send_mail`` will raise

      an ``smtplib.SMTPException``. See the `smtplib docs`_ for a list of

      possible exceptions, all of which are subclasses of ``SMTPException``.

    * ``auth_user``: The optional username to use to authenticate to the SMTP

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

      ``EMAIL_HOST_USER`` setting.

    * ``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.

.. _smtplib docs: http://www.python.org/doc/current/lib/module-smtplib.html

send_mass_mail()

================

``django.core.mail.send_mass_mail()`` is intended to handle mass e-mailing.

Here's the definition::

    send_mass_mail(datatuple, fail_silently=False,

        auth_user=None, auth_password=None):

``datatuple`` is a tuple in which each element is in this format::

    (subject, message, from_email, recipient_list)

``fail_silently``, ``auth_user`` and ``auth_password`` have the same functions

as in ``send_mail()``.

Each separate element of ``datatuple`` results in a separate e-mail message.

As in ``send_mail()``, recipients in the same ``recipient_list`` will all see

the other addresses in the e-mail messages's "To:" field.

send_mass_mail() vs. send_mail()

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

The main difference between ``send_mass_mail()`` and ``send_mail()`` is that

``send_mail()`` opens a connection to the mail server each time it's executed,

while ``send_mass_mail()`` uses a single connection for all of its messages.

This makes ``send_mass_mail()`` slightly more efficient.

mail_admins()

=============

``django.core.mail.mail_admins()`` is a shortcut for sending an e-mail to the

site admins, as defined in the `ADMINS setting`_. Here's the definition::

    mail_admins(subject, message, fail_silently=False)

``mail_admins()`` prefixes the subject with the value of the

`EMAIL_SUBJECT_PREFIX setting`_, which is ``"[Django] "`` by default.

The "From:" header of the e-mail will be the value of the `SERVER_EMAIL setting`_.

This method exists for convenience and readability.

.. _ADMINS setting: ../settings/#admins

.. _EMAIL_SUBJECT_PREFIX setting: ../settings/#email-subject-prefix

.. _SERVER_EMAIL setting: ../settings/#server-email

mail_managers() function

========================

``django.core.mail.mail_managers()`` is just like ``mail_admins()``, except it

sends an e-mail to the site managers, as defined in the `MANAGERS setting`_.

Here's the definition::

    mail_managers(subject, message, fail_silently=False)

.. _MANAGERS setting: ../settings/#managers

Examples

========

This sends a single e-mail to john@example.com and jane@example.com, with them

both appearing in the "To:"::

    send_mail('Subject', 'Message.', 'from@example.com',

        ['john@example.com', 'jane@example.com'])

This sends a message to john@example.com and jane@example.com, with them both

receiving a separate e-mail::

    datatuple = (

        ('Subject', 'Message.', 'from@example.com', ['john@example.com']),

        ('Subject', 'Message.', 'from@example.com', ['jane@example.com']),

    )

    send_mass_mail(datatuple)

Preventing header injection

===========================

`Header injection`_ is a security exploit in which an attacker inserts extra

e-mail headers to control the "To:" and "From:" in e-mail messages that your

scripts generate.

The Django e-mail functions outlined above all protect against header injection

by forbidding newlines in header values. If any ``subject``, ``from_email`` or

``recipient_list`` contains a newline (in either Unix, Windows or Mac style),

the e-mail function (e.g. ``send_mail()``) will raise

``django.core.mail.BadHeaderError`` (a subclass of ``ValueError``) and, hence,

will not send the e-mail. It's your responsibility to validate all data before

passing it to the e-mail functions.

If a ``message`` contains headers at the start of the string, the headers will

simply be printed as the first bit of the e-mail message.

Here's an example view that takes a ``subject``, ``message`` and ``from_email``

from the request's POST data, sends that to admin@example.com and redirects to

"/contact/thanks/" when it's done::

    from django.core.mail import send_mail, BadHeaderError

    def send_email(request):

        subject = request.POST.get('subject', '')

        message = request.POST.get('message', '')

        from_email = request.POST.get('from_email', '')

        if subject and message and from_email:

            try:

                send_mail(subject, message, from_email, ['admin@example.com'])

            except BadHeaderError:

                return HttpResponse('Invalid header found.')

            return HttpResponseRedirect('/contact/thanks/')

        else:

            # In reality we'd use a manipulator

            # to get proper validation errors.

            return HttpResponse('Make sure all fields are entered and valid.')

.. _Header injection: http://securephp.damonkohler.com/index.php/Email_Injection