Отправка электронной почты¶

send_mass_mail() против send_mail()¶

Основное различие между send_mass_mail() и send_mail() заключается в том, что send_mail() при каждом выполнении открывает соединение с почтовым сервером, в то время как send_mass_mail() использует одно соединение для всех своих сообщений. Это делает send_mass_mail() немного более эффективной.

EmailMessage Объекты¶

class EmailMessage[исходный код]¶

Класс EmailMessage инициализируется следующими параметрами (в указанном порядке, если используются позиционные аргументы). Все параметры являются необязательными и могут быть установлены в любое время до вызова метода send().

• subject: Тема письма.
• body: Основной текст. Это должно быть обычное текстовое сообщение.
• from_email: Адрес отправителя. Обе формы fred@example.com и "Fred" <fred@example.com> являются законными. Если опущено, то используется параметр DEFAULT_FROM_EMAIL.
• to: Список или кортеж адресов получателей.
• bcc: Список или кортеж адресов, используемых в заголовке «Bcc» при отправке письма.
• connection: Экземпляр бэкенда электронной почты. Используйте этот параметр, если вы хотите использовать одно и то же соединение для нескольких сообщений. Если параметр опущен, то при вызове send() создается новое соединение.
• attachments: Список вложений, которые следует поместить в сообщение. Это могут быть либо MIMEBase экземпляры, либо (filename, content, mimetype) тройки.
• headers: Словарь дополнительных заголовков для размещения в сообщении. Ключи - это имена заголовков, значения - это значения заголовков. Вызывающая сторона должна убедиться, что имена и значения заголовков имеют правильный формат для сообщения электронной почты. Соответствующим атрибутом является extra_headers.
• cc: Список или кортеж адресов получателей, используемых в заголовке «Cc» при отправке письма.
• reply_to: Список или кортеж адресов получателей, используемых в заголовке «Reply-To» при отправке электронной почты.

Например:

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

Класс имеет следующие методы:

• send(fail_silently=False) отправляет сообщение. Если при создании письма было указано соединение, будет использовано это соединение. В противном случае будет создан и использован экземпляр бэкенда по умолчанию. Если аргумент ключевого слова fail_silently равен True, исключения, возникшие при отправке сообщения, будут устранены. Пустой список получателей не вызовет исключения. Будет возвращено 1, если сообщение было отправлено успешно, иначе 0.

• message() создает объект django.core.mail.SafeMIMEText (подкласс класса Python MIMEText) или объект django.core.mail.SafeMIMEMultipart, содержащий сообщение для отправки. Если вам когда-нибудь понадобится расширить класс EmailMessage, вы, вероятно, захотите переопределить этот метод, чтобы поместить нужное вам содержимое в объект MIME.

• recipients() возвращает список всех получателей сообщения, независимо от того, записаны ли они в атрибутах to, cc или bcc. Это еще один метод, который вам, возможно, придется переопределить при создании подкласса, поскольку SMTP-серверу необходимо сообщить полный список получателей при отправке сообщения. Если в своем классе вы добавите другой способ указания получателей, они также должны быть возвращены из этого метода.

• attach() создает новое вложение файла и добавляет его к сообщению. Существует два способа вызова attach():

  • Вы можете передать ему единственный аргумент, который является экземпляром MIMEBase. Он будет вставлен непосредственно в результирующее сообщение.

  • В качестве альтернативы вы можете передать attach() три аргумента: filename, content и mimetype. filename - это имя вложения файла, которое будет отображаться в письме, content - это данные, которые будут содержаться во вложении, а mimetype - это необязательный MIME тип для вложения. Если вы опустите mimetype, тип содержимого MIME будет определяться по имени файла вложения.

    Например:

    message.attach('design.png', img_data, 'image/png')
    

    Если вы укажете mimetype из message/rfc822, он также примет django.core.mail.EmailMessage и email.message.Message.

    Для mimetype, начинающегося с text/, ожидается, что содержимое будет строкой. Двоичные данные будут декодированы с помощью UTF-8, и если это не удастся, MIME-тип будет изменен на application/octet-stream, а данные будут присоединены без изменений.

    Кроме того, вложения message/rfc822 больше не будут кодироваться base64 в нарушение RFC 2046#section-5.2.1, что может вызвать проблемы с отображением вложений в Evolution и Thunderbird.

• attach_file() создает новое вложение, используя файл из вашей файловой системы. Вызовите эту команду, указав путь к файлу, который нужно прикрепить, и, по желанию, MIME-тип, который нужно использовать для вложения. Если MIME-тип не указан, он будет определен из имени файла. Вы можете использовать его следующим образом:

  message.attach_file('/images/weather_map.png')
  

  Для типов MIME, начинающихся с text/, двоичные данные обрабатываются как в attach().

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

Получение экземпляра бэкенда электронной почты¶

Функция get_connection() в django.core.mail возвращает экземпляр почтового бэкенда, который вы можете использовать.

get_connection(backend=None, fail_silently=False, *args, **kwargs)[исходный код]¶

По умолчанию вызов get_connection() возвращает экземпляр почтового бэкенда, указанного в EMAIL_BACKEND. Если вы укажете аргумент backend, будет инстанцирован экземпляр этого бэкенда.

Аргумент fail_silently управляет тем, как бэкенд должен обрабатывать ошибки. Если fail_silently равен True, то исключения в процессе отправки письма будут молча игнорироваться.

Все остальные аргументы передаются непосредственно в конструктор почтового бэкенда.

Django поставляется с несколькими бэкендами для отправки электронной почты. За исключением бэкенда SMTP (который используется по умолчанию), эти бэкенды полезны только во время тестирования и разработки. Если у вас есть особые требования к отправке электронной почты, вы можете write your own email backend.

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'

Определение пользовательского бэкенда электронной почты¶

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

Пользовательские почтовые бэкенды должны иметь подкласс BaseEmailBackend, который находится в модуле django.core.mail.backends.base. Пользовательский почтовый бэкенд должен реализовать метод send_messages(email_messages). Этот метод получает список экземпляров EmailMessage и возвращает количество успешно доставленных сообщений. Если ваш бэкенд имеет какое-либо понятие о постоянном сеансе или соединении, вы также должны реализовать методы open() и close(). Эталонная реализация приведена в разделе smtp.EmailBackend.

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

Создание и закрытие SMTP-соединения (или любого другого сетевого соединения, если на то пошло) - дорогостоящий процесс. Если вам нужно отправить много писем, имеет смысл повторно использовать SMTP-соединение, а не создавать и уничтожать соединение каждый раз, когда вы хотите отправить письмо.

Есть два способа указать бэкенду электронной почты на повторное использование соединения.

Во-первых, вы можете использовать метод send_messages(). send_messages() принимает список экземпляров EmailMessage (или подклассов) и отправляет их все, используя одно соединение.

Например, если у вас есть функция get_notification_email(), которая возвращает список объектов EmailMessage, представляющих некоторые периодические электронные письма, которые вы хотите разослать, вы можете отправить эти письма с помощью одного вызова send_messages:

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

В этом примере вызов send_messages() открывает соединение на бэкенде, отправляет список сообщений, а затем снова закрывает соединение.

Второй подход заключается в использовании методов open() и close() на бэкенде электронной почты для ручного управления соединением. send_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()