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: Список, или кортеж, получателей.

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

• cc: Список, или кортеж, получателей, которые будут указаны в заголовке «Cc».

• bcc: Список, или кортеж, адресов, которые будут указаны в заголовке «Bcc».

• reply_to: Список, или кортеж, получателей, которые будут указаны в заголовке «Reply-To».

• attachments: список вложений, которые можно добавить к сообщению. Каждый из них может быть экземпляром MIMEPart или EmailAttachment, или кортежем с атрибутами (имя файла, содержимое, mimetype).

  Changed in Django 5.2:

  Добавлена ​​поддержка элементов EmailAttachment в вложениях.

  Changed in Django 6.0:

  Добавлена ​​поддержка объектов MIMEPart в списке attachments.

  Не рекомендуется, начиная с версии 6.0: Поддержка устаревших объектов Python MIMEBase во вложениях устарела. Вместо этого используйте MIMEPart.

• headers: Словарь дополнительных заголовков. Ключами являются названия заголовков, значения – содержимое заголовка. Вы сами должны убедиться в правильности заголовков. Соответствующий атрибут – extra_headers.

• connection: экземпляр email backend. Используйте этот параметр, если вы отправляете EmailMessage через send() и хотите использовать одно и то же соединение для нескольких сообщений. Если этот параметр опущен, новое соединение создается при вызове send(). Этот параметр игнорируется при использовании send_messages().

Не рекомендуется, начиная с версии 6.0: Передача всех параметров, кроме первых четырех, в качестве позиционных аргументов не рекомендуется.

Например:

from django.core.mail import EmailMessage

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

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

send(fail_silently=False)¶

Отправляет сообщение. Если соединение было указано при создании электронного письма, оно будет использоваться. В противном случае будет создан и использован экземпляр серверной части по умолчанию. Если аргумент ключевого слова fail_silly равен True, исключения, возникшие при отправке сообщения, будут отменены. Пустой список получателей не вызовет исключения. Он вернет «1», если сообщение было отправлено успешно, в противном случае — «0».

message(policy=email.policy.default)¶

Создает и возвращает объект Python email.message.EmailMessage, представляющий отправляемое сообщение.

Аргумент ключевого слова policy позволяет указать набор правил для обновления и сериализации представления сообщения. Это должен быть объект email.policy.Policy. По умолчанию: data:email.policy.default. В некоторых случаях вы можете использовать SMTP, SMTPUTF8 или пользовательскую политику. Например, django.core.mail.backends.smtp.EmailBackend использует политику SMTP для обеспечения окончания строк \r\n, как того требует протокол SMTP.

Если вам когда-нибудь понадобится расширить класс EmailMessage Django, вы, вероятно, захотите переопределить этот метод, чтобы поместить нужное вам содержимое в объект Python EmailMessage.

Changed in Django 6.0:

Был добавлен аргумент ключевого слова policy, а тип возвращаемого значения был обновлен до экземпляра EmailMessage.

recipients()¶

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

attach(filename, content, mimetype)¶

attach(mimepart)

Создает новое вложение и добавляет его в сообщение. Есть два способа вызвать attach():

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

  Например:

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

  Если вы укажете mimetype message/rfc822, content может быть django.core.mail.EmailMessage или email.message.EmailMessage или email.message.Message в Python.

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

• Или для вложений, требующих дополнительных заголовков или параметров, вы можете передать attach() один объект Python MIMEPart. Это будет прикреплено непосредственно к полученному сообщению. Например, чтобы прикрепить встроенное изображение с Content-ID:

  import email.utils
  from email.message import MIMEPart
  from django.core.mail import EmailMultiAlternatives
  
  message = EmailMultiAlternatives(...)
  image_data_bytes = ...  # Load image as bytes
  
  # Create a random Content-ID, including angle brackets
  cid = email.utils.make_msgid()
  inline_image = email.message.MIMEPart()
  inline_image.set_content(
      image_data_bytes,
      maintype="image",
      subtype="png",  # or "jpeg", etc. depending on the image type
      disposition="inline",
      cid=cid,
  )
  message.attach(inline_image)
  # Refer to Content-ID in HTML without angle brackets
  message.attach_alternative(f'… <img src="cid:{cid[1:-1]}"> …', "text/html")
  

  Документация Python email.contentmanager.set_content() описывает поддерживаемые аргументы для MIMEPart.set_content().

  Changed in Django 6.0:

  Добавлена ​​поддержка вложений MIMEPart.

  Не рекомендуется, начиная с версии 6.0: Поддержка вложений email.mime.base.MIMEBase устарела. Вместо этого используйте MIMEPart.

attach_file(path, mimetype=None)¶

Создает новое вложение, используя файл из вашей файловой системы. Вызовите его, указав путь к прикрепляемому файлу и, при необходимости, тип MIME, который будет использоваться для вложения. Если тип MIME опущен, он будет угадываться по имени файла. Вы можете использовать его так:

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

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

class EmailAttachment¶

New in Django 5.2.

Именованный кортеж для хранения вложений к электронному письму.

Именованный кортеж имеет следующие индексы:

• имя файла

• содержание

• миметип

Отправка содержимого разного типа¶

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, **kwargs)¶

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

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

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

Django предоставляет несколько бэкендов. Эти бэкенды, кроме SMTP (который используется по умолчанию), полезны только при разработке или тестировании. Вы можете создать собственный бэкенд.

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 необходимо указать путь для импорта класса вашего бэкенда.

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

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

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

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

Во-первых, вы можете использовать метод send_messages() для соединения. Это берет список экземпляров EmailMessage (или подкласса) и отправляет их все, используя одно соединение. Как следствие, любое соединение <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()