Отправка электронных писем

Быстрые примеры

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

from django.core.mail import send_mail

send_mail(
    "Subject here",
    "Here is the message.",
    "from@example.com",
    ["to@example.com"],
    fail_silently=False,
)

Когда требуется дополнительная функциональность для отправки электронных писем, используйте EmailMessage или EmailMultiAlternatives. Например, чтобы отправить многочастьное электронное письмо, которое включает как HTML, так и текстовые версии с определённой шаблоном и пользовательскими заголовками, вы можете использовать следующий подход:

from django.core.mail import EmailMultiAlternatives
from django.template.loader import render_to_string

# First, render the plain text content.
text_content = render_to_string(
    "templates/emails/my_email.txt",
    context={"my_variable": 42},
)

# Secondly, render the HTML content.
html_content = render_to_string(
    "templates/emails/my_email.html",
    context={"my_variable": 42},
)

# Then, create a multipart email instance.
msg = EmailMultiAlternatives(
    "Subject here",
    text_content,
    "from@example.com",
    ["to@example.com"],
    headers={"List-Unsubscribe": "<mailto:unsub@example.com>"},
)

# Lastly, attach the HTML content to the email instance and send.
msg.attach_alternative(html_content, "text/html")
msg.send()

Почта отправляется с использованием 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) [source]

В большинстве случаев вы можете отправлять электронные письма с помощью django.core.mail.send_mail().

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

• subject: Строка.
• message: Строка.
• from_email: Строка. Если None, Django будет использовать значение настройки DEFAULT_FROM_EMAIL.
• recipient_list: Список строк, каждая из которых — электронный адрес. Каждый член recipient_list увидит других получателей в поле «Кому» сообщения электронного письма.
• 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) [source]

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 увидят все остальные адреса в поле «Кому» сообщений электронных писем.

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

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) [source]

django.core.mail.mail_admins() — это сокращение для отправки электронного письма администраторам сайта, как определено в настройке ADMINS.

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

Заголовок «От кого» электронного письма будет равен значению настройки 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) [source]

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

Примеры

Это отправляет одно электронное письмо на john@example.com и jane@example.com, при этом оба будут отображаться в поле «Кому»:

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)

Предотвращение инъекции заголовков

Инъекция заголовков — это уязвимость, при которой злоумышленник вставляет дополнительные заголовки электронной почты для управления полями «Кому» и «От» в сообщениях электронной почты, генерируемых вашими скриптами.

Все функции 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

Функции Django send_mail() и send_mass_mail() на самом деле являются тонкими оболочками, использующими класс EmailMessage.

Не все возможности класса EmailMessage доступны через функции send_mail() и аналогичные обертки. Если вам нужны расширенные возможности, такие как адресате с функцией BCC, вложения файлов или многочастьные письма, вам необходимо создавать экземпляры 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"},
)

Email-серверы

Фактическое отправление электронного письма обрабатывается сервером электронной почты.

Класс сервера электронной почты имеет следующие методы:

• open() инициализирует долговременное соединение для отправки электронных писем.
• close() закрывает текущее соединение для отправки электронных писем.
• send_messages(email_messages) отправляет список объектов EmailMessage. Если соединение не открыто, этот вызов неявно откроет соединение и закроет его после отправки почты. Если соединение уже открыто, оно останется открытым после отправки писем.

Он также может использоваться как менеджер контекста, который автоматически вызовет 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 отправлял электронные письма вообще. Например, при разработке веб-сайта, вероятно, вы не захотите отправлять тысячи писем — но вы можете захотеть проверить, что письма будут отправляться нужным людям при соответствующих условиях и что эти письма будут содержать правильное содержание.

Самый простой способ настроить электронную почту для локальной разработки — использовать почтовый бэкэнд консоли. Этот бэкэнд перенаправляет все электронные письма в stdout, позволяя вам проверить содержимое почты.

Почтовый бэкэнд файла также может быть полезен во время разработки — этот бэкэнд записывает содержимое каждого SMTP-соединения в файл, который можно просмотреть по своему усмотрению.

Другой подход заключается в использовании «простого» SMTP-сервера, который принимает электронные письма локально и отображает их в терминале, но фактически ничего не отправляет. Пакет aiosmtpd предоставляет способ достижения этого:

python -m pip install aiosmtpd

python -m aiosmtpd -n -l localhost:8025

Эта команда запустит минимальный SMTP-сервер, слушающий на порту 8025 localhost. Этот сервер выводит в стандартный вывод все заголовки электронных писем и тело письма. Вам нужно только установить EMAIL_HOST и EMAIL_PORT соответственно. Более подробное описание параметров SMTP-сервера см. в документации модуля aiosmtpd.

Дополнительную информацию об отладке отправки электронных писем в вашем приложении см. в разделе Услуги электронной почты документации по тестированию.