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

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, либо кортежем с атрибутами (filename, content, mimetype).

  Изменено в Django 5.2:

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

  Изменено в Django 6.0:

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

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

• headers: Словарь дополнительных заголовков для добавления к сообщению. Ключи — это имена заголовков, значения — значения заголовков. Вызывающий код должен обеспечить соответствие имён и значений заголовков правильному формату для сообщения электронной почты. Соответствующий атрибут — extra_headers.
• connection: Экземпляр бэкенда электронной почты. Используйте этот параметр, если отправляете 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_silently имеет значение True, исключения, возникающие при отправке сообщения, будут подавлены. Пустой список получателей не вызовет исключения. Метод вернёт 1, если сообщение было успешно отправлено, и 0 в противном случае.

message(policy=email.policy.default) [исходный код]

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

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

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

Изменено в 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, Python email.message.EmailMessage или email.message.Message.

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

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

  cid = email.utils.make_msgid()
  inline_image = email.message.MIMEPart()
  inline_image.set_content(
      image_data_bytes,
      maintype="image",
      subtype="png",
      disposition="inline",
      cid=f"<{cid}>",
  )
  message.attach(inline_image)
  message.attach_alternative(f'… <img src="cid:${cid}"> …', "text/html")
  

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

  Изменено в 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

Добавлено в Django 5.2.

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

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

• filename
• content
• mimetype

Отправка содержимого в альтернативных форматах

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_silently, который можно передать только по имени, определяет, как бэкенд должен обрабатывать ошибки. Если fail_silently имеет значение 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 в файле настроек будет путь импорта Python для класса бэкенда.

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

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

Установка и закрытие соединения SMTP (или любого другого сетевого соединения) — затратная операция. Если вам нужно отправить много писем, имеет смысл повторно использовать соединение SMTP, а не создавать и закрывать его каждый раз при отправке письма.

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

Во-первых, можно использовать метод send_messages() для соединения. Он принимает список экземпляров EmailMessage (или подкласса) и отправляет их все через одно соединение. Поэтому любые значения connection, заданные для отдельных сообщений, игнорируются.

Например, если у вас есть функция 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()