Sending e-mail

These docs are frozen for Django version 0.91. For current documentation, go here.

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.

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)

The send_mail function

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=EMAIL_HOST_USER,
    auth_password=EMAIL_HOST_PASSWORD)

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: New in Django development version. 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: New in Django development version. 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.

The send_mass_mail function

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=EMAIL_HOST_USER, auth_password=EMAIL_HOST_PASSWORD):

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(). Note that auth_user and auth_password are only available in the Django development version.

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.

The mail_admins function

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.

The 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)

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.')

Django documentation