plain.mail

  1"""
  2Tools for sending email.
  3"""
  4
  5from plain.runtime import settings
  6from plain.utils.module_loading import import_string
  7
  8from .message import (
  9    DEFAULT_ATTACHMENT_MIME_TYPE,
 10    BadHeaderError,
 11    EmailMessage,
 12    EmailMultiAlternatives,
 13    SafeMIMEMultipart,
 14    SafeMIMEText,
 15    TemplateEmail,
 16    forbid_multi_line_headers,
 17    make_msgid,
 18)
 19from .utils import DNS_NAME, CachedDnsName
 20
 21__all__ = [
 22    "CachedDnsName",
 23    "DNS_NAME",
 24    "EmailMessage",
 25    "EmailMultiAlternatives",
 26    "TemplateEmail",
 27    "SafeMIMEText",
 28    "SafeMIMEMultipart",
 29    "DEFAULT_ATTACHMENT_MIME_TYPE",
 30    "make_msgid",
 31    "BadHeaderError",
 32    "forbid_multi_line_headers",
 33    "get_connection",
 34    "send_mail",
 35    "send_mass_mail",
 36]
 37
 38
 39def get_connection(backend=None, fail_silently=False, **kwds):
 40    """Load an email backend and return an instance of it.
 41
 42    If backend is None (default), use settings.EMAIL_BACKEND.
 43
 44    Both fail_silently and other keyword arguments are used in the
 45    constructor of the backend.
 46    """
 47    klass = import_string(backend or settings.EMAIL_BACKEND)
 48    return klass(fail_silently=fail_silently, **kwds)
 49
 50
 51def send_mail(
 52    subject,
 53    message,
 54    from_email,
 55    recipient_list,
 56    fail_silently=False,
 57    auth_user=None,
 58    auth_password=None,
 59    connection=None,
 60    html_message=None,
 61):
 62    """
 63    Easy wrapper for sending a single message to a recipient list. All members
 64    of the recipient list will see the other recipients in the 'To' field.
 65
 66    If from_email is None, use the EMAIL_DEFAULT_FROM setting.
 67    If auth_user is None, use the EMAIL_HOST_USER setting.
 68    If auth_password is None, use the EMAIL_HOST_PASSWORD setting.
 69
 70    Note: The API for this method is frozen. New code wanting to extend the
 71    functionality should use the EmailMessage class directly.
 72    """
 73    connection = connection or get_connection(
 74        username=auth_user,
 75        password=auth_password,
 76        fail_silently=fail_silently,
 77    )
 78    mail = EmailMultiAlternatives(
 79        subject, message, from_email, recipient_list, connection=connection
 80    )
 81    if html_message:
 82        mail.attach_alternative(html_message, "text/html")
 83
 84    return mail.send()
 85
 86
 87def send_mass_mail(
 88    datatuple, fail_silently=False, auth_user=None, auth_password=None, connection=None
 89):
 90    """
 91    Given a datatuple of (subject, message, from_email, recipient_list), send
 92    each message to each recipient list. Return the number of emails sent.
 93
 94    If from_email is None, use the EMAIL_DEFAULT_FROM setting.
 95    If auth_user and auth_password are set, use them to log in.
 96    If auth_user is None, use the EMAIL_HOST_USER setting.
 97    If auth_password is None, use the EMAIL_HOST_PASSWORD setting.
 98
 99    Note: The API for this method is frozen. New code wanting to extend the
100    functionality should use the EmailMessage class directly.
101    """
102    connection = connection or get_connection(
103        username=auth_user,
104        password=auth_password,
105        fail_silently=fail_silently,
106    )
107    messages = [
108        EmailMessage(subject, message, sender, recipient, connection=connection)
109        for subject, message, sender, recipient in datatuple
110    ]
111    return connection.send_messages(messages)