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

.. py:module:: util.email

.. autoapi-nested-parse::

   Email utility classes and functions for rendering and sending templates.



Attributes
----------

.. autoapisummary::

   util.email.Attachment


Classes
-------

.. autoapisummary::

   util.email.MailTemplate
   util.email.MailTemplates
   util.email.EmailPayload


Functions
---------

.. autoapisummary::

   util.email._render_bodies
   util.email.send_email
   util.email.send_bulk


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:class:: EmailPayload

   Immutable value object describing one outbound email.

   .. attribute:: subject

      Subject line.

   .. attribute:: to

      Recipients.

   .. attribute:: template_html

      Django template path for the HTML body.

   .. 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:method:: __post_init__()

      Validate and normalize fields after dataclass initialization.

      Ensures that mapping/sequence attributes are immutable wrappers or tuples.



.. py:function:: _render_bodies(tpl, context)

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

   Send a single email with HTML + text alternative.

   :returns: Number of successfully delivered messages (0 or 1).


.. py:function:: send_bulk(payloads)

   Send multiple emails reusing one SMTP connection.