util.email

Email utility classes and functions for rendering and sending templates.

Attributes

Attachment

Classes

MailTemplate

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

MailTemplates

Registry of grouped mail templates.

EmailPayload

Immutable value object describing one outbound email.

Functions

_render_bodies(tpl, context)

send_email(payload, *[, connection])

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

send_simple(*, subject, body, to[, cc, bcc, ...])

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

normalize_addresses(value)

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

send_bulk(payloads)

Send multiple template-based emails reusing one SMTP connection.

Module Contents

util.email.Attachment[source]
class util.email.MailTemplate[source]

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

key: str[source]
base: str[source]
label: str[source]
txt()[source]

Return the plain-text template path.

Return type:

str

html()[source]

Return the HTML template path.

Return type:

str

class util.email.MailTemplates[source]

Registry of grouped mail templates.

USER_WELCOME: ClassVar[MailTemplate][source]
USER_DELETE: ClassVar[MailTemplate][source]
CERTIFICATE_ISSUED: ClassVar[MailTemplate][source]
CERTIFICATE_REVOKED: ClassVar[MailTemplate][source]
GROUPS: ClassVar[collections.abc.Mapping[str, tuple[MailTemplate, Ellipsis]]][source]
classmethod get_user_templates()[source]

Return the list of user-related templates.

Return type:

list[MailTemplate]

classmethod get_certificate_templates()[source]

Return the list of certificate-related templates.

Return type:

list[MailTemplate]

classmethod all()[source]

Return all templates for all groups.

Return type:

list[MailTemplate]

classmethod get_by_key(key)[source]

Find a template by its key.

Parameters:

key (str)

Return type:

MailTemplate | None

class util.email.EmailPayload[source]

Immutable value object describing one outbound email.

subject[source]

Subject line.

to[source]

Recipients.

template_html[source]

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

context[source]

Template context (wrapped as read-only).

from_email[source]

Optional override; defaults to settings.DEFAULT_FROM_EMAIL.

reply_to[source]

Optional Reply-To addresses.

cc[source]

Optional CC recipients.

bcc[source]

Optional BCC recipients.

attachments[source]

Optional sequence of (filename, bytes, mimetype).

headers[source]

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

subject: str[source]
to: tuple[str, Ellipsis][source]
template_html: MailTemplate[source]
context: collections.abc.Mapping[str, object][source]
from_email: str | None = None[source]
reply_to: tuple[str, Ellipsis] = ()[source]
cc: tuple[str, Ellipsis] = ()[source]
bcc: tuple[str, Ellipsis] = ()[source]
attachments: tuple[Attachment, Ellipsis] = ()[source]
headers: collections.abc.Mapping[str, str][source]
__post_init__()[source]

Validate and normalize fields after dataclass initialization.

Return type:

None

util.email._render_bodies(tpl, context)[source]
Parameters:

  • tpl (MailTemplate)

  • context (collections.abc.Mapping[str, object])

Return type:

tuple[str, str]

util.email.send_email(payload, *, connection=None)[source]

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

Parameters:
Return type:

int

util.email.send_simple(*, subject, body, to, cc=(), bcc=(), from_email=None, connection=None, attachments=())[source]

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

Parameters:

  • subject (str)

  • body (str)

  • to (collections.abc.Iterable[str])

  • cc (collections.abc.Iterable[str])

  • bcc (collections.abc.Iterable[str])

  • from_email (str | None)

  • connection (Any)

  • attachments (collections.abc.Iterable[Attachment])

Return type:

int

util.email.normalize_addresses(value)[source]

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

Parameters:

value (Any)

Return type:

tuple[str, Ellipsis]

util.email.send_bulk(payloads)[source]

Send multiple template-based emails reusing one SMTP connection.

Parameters:

payloads (collections.abc.Iterable[EmailPayload])

Return type:

int