Примеры¶

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

Письмо отправлено через SMTP хост и порт, которые указаны в настройках EMAIL_HOST и EMAIL_PORT. Настройки EMAIL_HOST_USER и EMAIL_HOST_PASSWORD, если указаны, используются для авторизации на SMTP сервере, а настройки EMAIL_USE_TLS и EMAIL_USE_SSL указывают использовать ли безопасное соединение.

send_mail()¶

send_mail(subject, message, from_email, recipient_list, fail_silently=False, auth_user=None, auth_password=None, connection=None, html_message=None)¶

Самый простой способ отправить письмо – использовать django.core.mail.send_mail().

Параметры subject, message, from_email и recipient_list являются обязательными.

• subject: строка.

• message: строка.

• from_email: строка. Если None, Django будет использовать значение параметра DEFAULT_FROM_EMAIL.

• recipient_list: список строк, каждая является email. Каждый получатель из recipient_list будет видеть остальных получателей в поле «To:» письма.

• fail_silently: булево. При False send_mail вызовет smtplib.SMTPException. Смотрите документацию smtplib, чтобы узнать список всех ошибок, каждый из которых наследуется от SMTPException.

• auth_user: необязательное имя пользователя, которое используется при авторизации на SMTP сервере. Если не указано, Django будет использовать значение EMAIL_HOST_USER.

• auth_password: необязательный пароль, который используется при авторизации на SMTP сервере. Если не указано, Django будет использовать значение EMAIL_HOST_PASSWORD.

• connection: необязательный бэкенд, который будет использоваться для отправки письма. Если не указан, будет использоваться бэкенд по умолчанию. Смотрите раздел о бэкендах для отправки электронной почты.

• html_message: если html_message указано, письмо будет с multipart/alternative, и будет содержать message с типом text/plain, и html_message с типом text/html.

Возвращает количество успешно отправленных писем (которое будет 0 или 1, т.к. функция отправляет только одно письмо).

send_mass_mail()¶

send_mass_mail(datatuple, fail_silently=False, auth_user=None, auth_password=None, connection=None)¶

django.core.mail.send_mass_mail() используется для массовой рассылки электронных писем.

datatuple – кортеж, каждый элемент которого следующего формата:

(subject, message, from_email, recipient_list)

fail_silently, auth_user и auth_password аналогичны параметрам send_mail().

Каждый элемент datatuple соответствует отдельному письму. Как и для send_mail(), получатели из одного списка recipient_list увидят всех остальных в поле «To:» письма.

Например, следующий код отправит два отдельных письма двум отдельным спискам получателей. Однако, будет использоваться одно подключения к почтовому серверу:

message1 = ('Subject here', 'Here is the message', 'from@example.com', ['first@example.com', 'other@example.com'])
message2 = ('Another Subject', 'Here is another message', 'from@example.com', ['second@test.com'])
send_mass_mail((message1, message2), fail_silently=False)

Возвращает количество успешно отправленных писем.

mail_admins()¶

mail_admins(subject, message, fail_silently=False, connection=None, html_message=None)¶

django.core.mail.mail_admins() отправляет письма администраторам сайта, которые указаны в настройке ADMINS.

mail_admins() к заголовку письма добавляет префикс из EMAIL_SUBJECT_PREFIX, по умолчанию "[Django] ".

Заголовок «From:» будет содержать значение SERVER_EMAIL.

Этот метод существует для удобства и читаемости.

Если указан html_message, письмо будет с multipart/alternative, и будет содержать message с типом text/plain, и html_message с типом text/html.

mail_managers()¶

mail_managers(subject, message, fail_silently=False, connection=None, html_message=None)¶

django.core.mail.mail_managers() аналогичен mail_admins(), но отправляет письма менеджерам сайта, которые указаны в MANAGERS.

Примеры¶

Отправляет одно письмо john@example.com и jane@example.com, они оба указаны в «To:»:

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

Отправляет письма john@example.com и jane@example.com, они получать отдельные письма:

datatuple = (
    ('Subject', 'Message.', 'from@example.com', ['john@example.com']),
    ('Subject', 'Message.', 'from@example.com', ['jane@example.com']),
)
send_mass_mail(datatuple)

Защищаемся от инъекции заголовков электронного письма¶

Инъекции заголовков – это атака, во время которой атакующий добавляет данные в заголовки письма «To:» и «From:», которое создает ваш код.

Функции для отправки писем в Django запрещают указывать перенос строки в значениях заголовков. Если subject, from_email или recipient_list содержит перенос строки (в Unix, Windows или Mac стиле), функция отправки писем (например, send_mail()) вызовет исключение django.core.mail.BadHeaderError (дочерний класс ValueError), и ничего не оправит. Это ваша ответственность проверять все данные перед тем, как передать в функцию.

Если message содержит заголовки в начале, они просто будут выведены в начале содержимого письма.

Вот пример представления, которое получает subject, message и from_email из POST данных запроса, отправляет их на admin@example.com, и перенаправляет по адресу «/contact/thanks/»:

from django.core.mail import BadHeaderError, send_mail
from django.http import HttpResponse, HttpResponseRedirect

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 form class
        # to get proper validation errors.
        return HttpResponse('Make sure all fields are entered and valid.')

Класс EmailMessage¶

Функции send_mail() и send_mass_mail() на самом деле обертки, которые используют класс EmailMessage.

Не все возможности EmailMessage доступны через send_mail() и остальные функции. Если вы хотите использовать дополнительные возможности, такие как получатели в BCC, отправка файла, или «multi-part» письмо, вам следует использовать непосредственно EmailMessage.

EmailMessage отвечает за создание электронного письма. Бэкенд отправки писем отвечает за отправку писем.

Для удобства EmailMessage предоставляет простой метод send() для отправки одного письма. Если вы хотите отправить несколько писем, API бэкенда предоставляет дополнительные методы.

from django.core.mail import EmailMessage

email = EmailMessage(
    'Hello',
    'Body goes here',
    'from@example.com',
    ['to1@example.com', 'to2@example.com'],
    ['bcc@example.com'],
    reply_to=['another@example.com'],
    headers={'Message-ID': 'foo'},
)

from django.core.mail import EmailMultiAlternatives

subject, from_email, to = 'hello', 'from@example.com', 'to@example.com'
text_content = 'This is an important message.'
html_content = '<p>This is an <strong>important</strong> message.</p>'
msg = EmailMultiAlternatives(subject, text_content, from_email, [to])
msg.attach_alternative(html_content, "text/html")
msg.send()

msg = EmailMessage(subject, html_content, from_email, [to])
msg.content_subtype = "html"  # Main content is now text/html
msg.send()

Бэкенды для отправки электронной почты¶

Непосредственная отправка электронного письма происходит в бэкенде.

Бэкенд содержит следующие методы:

• open() создает длительное соединение.

• close() закрывает текущее соединение.

• send_messages(email_messages) sends a list of EmailMessage objects. If the connection is not open, this call will implicitly open the connection, and close the connection afterwards. If the connection is already open, it will be left open after mail has been sent.

Может использоваться как контекстный менеджер, автоматически вызывая open() и close() при необходимости:

from django.core import mail

with mail.get_connection() as connection:
    mail.EmailMessage(
        subject1, body1, from1, [to1],
        connection=connection,
    ).send()
    mail.EmailMessage(
        subject2, body2, from2, [to2],
        connection=connection,
    ).send()

EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'

EMAIL_BACKEND = 'django.core.mail.backends.filebased.EmailBackend'
EMAIL_FILE_PATH = '/tmp/app-messages' # change this to a proper location

EMAIL_BACKEND = 'django.core.mail.backends.locmem.EmailBackend'

EMAIL_BACKEND = 'django.core.mail.backends.dummy.EmailBackend'

from django.core import mail
connection = mail.get_connection()   # Use default email connection
messages = get_notification_email()
connection.send_messages(messages)

from django.core import mail
connection = mail.get_connection()

# Manually open the connection
connection.open()

# Construct an email 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

# Construct two more messages
email2 = mail.EmailMessage(
    'Hello',
    'Body goes here',
    'from@example.com',
    ['to2@example.com'],
)
email3 = mail.EmailMessage(
    'Hello',
    'Body goes here',
    'from@example.com',
    ['to3@example.com'],
)

# Send the two emails 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.
connection.close()

Настройка почты при разработке¶

Иногда вы не хотите, чтобы Django отправлял почту. Например, при разработке сайта. Вряд ли вы захотите отправлять тысячи писем, но при этом необходимо проверить, что код их отправляет правильным получателям с правильным содержимым.

The easiest way to configure email for local development is to use the console email backend. This backend redirects all email to stdout, allowing you to inspect the content of mail.

Также можно использовать file. Этот бэкенд сохраняет содержимое каждого SMTP-соединения в файл.

Another approach is to use a «dumb» SMTP server that receives the emails locally and displays them to the terminal, but does not actually send anything. Python has a built-in way to accomplish this with a single command:

python -m smtpd -n -c DebuggingServer localhost:1025

This command will start a minimal SMTP server listening on port 1025 of localhost. This server prints to standard output all email headers and the email body. You then only need to set the EMAIL_HOST and EMAIL_PORT accordingly. For a more detailed discussion of SMTP server options, see the Python documentation for the smtpd module.

Информацию об отправке электронной почты при тестировании смотрите в разделе Сервисы для отправки писем.