1 ==============

     2 Sending e-mail

     3 ==============

     4 

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

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

     7 extra quick.

     8 

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

    10 

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

    12 

    13 Quick example

    14 =============

    15 

    16 In two lines::

    17 

    18     from django.core.mail import send_mail

    19 

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

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

    22         

    23 .. note::

    24 

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

    26     the value of your `DEFAULT_CHARSET setting`_.

    27     

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

    29 

    30 send_mail()

    31 ===========

    32 

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

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

    35 

    36     send_mail(subject, message, from_email, recipient_list,

    37         fail_silently=False, auth_user=None,

    38         auth_password=None)

    39 

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

    41 are required.

    42 

    43     * ``subject``: A string.

    44     * ``message``: A string.

    45     * ``from_email``: A string.

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

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

    48       field of the e-mail message.

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

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

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

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

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

    54       ``EMAIL_HOST_USER`` setting.

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

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

    57       ``EMAIL_HOST_PASSWORD`` setting.

    58 

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

    60 

    61 send_mass_mail()

    62 ================

    63 

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

    65 Here's the definition::

    66 

    67     send_mass_mail(datatuple, fail_silently=False,

    68         auth_user=None, auth_password=None):

    69 

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

    71 

    72     (subject, message, from_email, recipient_list)

    73 

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

    75 as in ``send_mail()``.

    76 

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

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

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

    80 

    81 send_mass_mail() vs. send_mail()

    82 --------------------------------

    83 

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

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

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

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

    88 

    89 mail_admins()

    90 =============

    91 

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

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

    94 

    95     mail_admins(subject, message, fail_silently=False)

    96 

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

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

    99 

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

   101 

   102 This method exists for convenience and readability.

   103 

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

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

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

   107 

   108 mail_managers() function

   109 ========================

   110 

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

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

   113 Here's the definition::

   114 

   115     mail_managers(subject, message, fail_silently=False)

   116 

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

   118 

   119 Examples

   120 ========

   121 

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

   123 both appearing in the "To:"::

   124 

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

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

   127 

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

   129 receiving a separate e-mail::

   130 

   131     datatuple = (

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

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

   134     )

   135     send_mass_mail(datatuple)

   136 

   137 Preventing header injection

   138 ===========================

   139 

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

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

   142 scripts generate.

   143 

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

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

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

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

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

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

   150 passing it to the e-mail functions.

   151 

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

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

   154 

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

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

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

   158 

   159     from django.core.mail import send_mail, BadHeaderError

   160 

   161     def send_email(request):

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

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

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

   165         if subject and message and from_email:

   166             try:

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

   168             except BadHeaderError:

   169                 return HttpResponse('Invalid header found.')

   170             return HttpResponseRedirect('/contact/thanks/')

   171         else:

   172             # In reality we'd use a manipulator

   173             # to get proper validation errors.

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

   175 

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