util.email
==========

.. py:module:: util.email

.. autoapi-nested-parse::

   Email utility classes and functions for rendering and sending templates.









Module Contents
---------------

.. py:data:: Attachment

.. py:class:: MailTemplate

   Represents a template base path with helpers for .txt and .html variants.


   .. py:attribute:: key
      :type:  str


   .. py:attribute:: base
      :type:  str


   .. py:attribute:: label
      :type:  str


   .. py:method:: txt()

      Return the plain-text template path.



   .. py:method:: html()

      Return the HTML template path.



.. py:class:: MailTemplates

   Registry of grouped mail templates.


   .. py:attribute:: USER_WELCOME
      :type:  ClassVar[MailTemplate]


   .. py:attribute:: USER_DELETE
      :type:  ClassVar[MailTemplate]


   .. py:attribute:: CERTIFICATE_ISSUED
      :type:  ClassVar[MailTemplate]


   .. py:attribute:: CERTIFICATE_REVOKED
      :type:  ClassVar[MailTemplate]


   .. py:attribute:: GROUPS
      :type:  ClassVar[collections.abc.Mapping[str, tuple[MailTemplate, Ellipsis]]]


   .. py:method:: get_user_templates()
      :classmethod:


      Return the list of user-related templates.



   .. py:method:: get_certificate_templates()
      :classmethod:


      Return the list of certificate-related templates.



   .. py:method:: all()
      :classmethod:


      Return all templates for all groups.



   .. py:method:: get_by_key(key)
      :classmethod:


      Find a template by its key.



.. py:class:: EmailPayload

   Immutable value object describing one outbound email.

   .. attribute:: subject

      Subject line.

   .. attribute:: to

      Recipients.

   .. attribute:: template_html

      Django template base (we render .txt and .html).

   .. attribute:: context

      Template context (wrapped as read-only).

   .. attribute:: from_email

      Optional override; defaults to settings.DEFAULT_FROM_EMAIL.

   .. attribute:: reply_to

      Optional Reply-To addresses.

   .. attribute:: cc

      Optional CC recipients.

   .. attribute:: bcc

      Optional BCC recipients.

   .. attribute:: attachments

      Optional sequence of (filename, bytes, mimetype).

   .. attribute:: headers

      Optional extra headers (e.g., {"X-Tag": "welcome"}).


   .. py:attribute:: subject
      :type:  str


   .. py:attribute:: to
      :type:  tuple[str, Ellipsis]


   .. py:attribute:: template_html
      :type:  MailTemplate


   .. py:attribute:: context
      :type:  collections.abc.Mapping[str, object]


   .. py:attribute:: from_email
      :type:  str | None
      :value: None



   .. py:attribute:: reply_to
      :type:  tuple[str, Ellipsis]
      :value: ()



   .. py:attribute:: cc
      :type:  tuple[str, Ellipsis]
      :value: ()



   .. py:attribute:: bcc
      :type:  tuple[str, Ellipsis]
      :value: ()



   .. py:attribute:: attachments
      :type:  tuple[Attachment, Ellipsis]
      :value: ()



   .. py:attribute:: headers
      :type:  collections.abc.Mapping[str, str]


.. py:function:: send_email(payload, *, connection = None)

   Send a single email with HTML + text alternative (from templates).


.. py:function:: send_simple(*, subject, body, to, cc = (), bcc = (), from_email = None, connection = None, attachments = ())

   Send a plain-text email without using a HTML/txt template pair.


.. py:function:: normalize_addresses(value)

   Accept CSV string or iterable; return tuple of non-empty, trimmed emails.


.. py:function:: send_bulk(payloads)

   Send multiple template-based emails reusing one SMTP connection.