Skip to content

common_reports.emails.base

BaseEmailClient — the email algebra (the engine, not a transport).

This base owns the pipelines and validation; the transport is an abstract seam. The split mirrors the package design:

PUBLIC pipelines (concrete here):
send(msg) -> SendResult validate -> context-merge -> _send seam
asend(msg) -> SendResult thread-offloaded send
read(...) -> ReadBatch validate -> _list seam
Abstract seams (filled by CoreEmailClient via a provider):
_send(mime, recipients) -> message_id
_list(folder, limit, unseen_only) -> list[ReadResult]

The engine does context resolution (From / Reply-To / signature / default recipients), recipient defaulting, structured logging and error capture; it delegates the actual MIME build to emails/composer.build_message and the wire effect to the _send / _list seams. Providers do effects only.

Classes

BaseEmailClient

Bases: ABC

Abstract read-write email client — pipelines concrete, transport abstract.

__init__

def __init__(context: Optional[EmailContext] = None, login_user: str = '', name: str = 'default')

Fields and properties declared here; inherited members belong to the bases above.

context

context = context or EmailContext()

logger

logger = structlog.get_logger(self.__class__.__name__).bind(account=name)

login_user

login_user = login_user

name

name = name

asend

async def asend(msg: EmailMessage) -> SendResult

Async send — offloads the blocking transport call to a thread.

inbox

def inbox(limit: int = 10, unseen_only: bool = False) -> ReadBatch

Convenience: read the INBOX folder.

read

def read(folder: str = 'INBOX', limit: int = 10, unseen_only: bool = False) -> ReadBatch

Read messages from a folder, newest first.

send

def send(msg: EmailMessage) -> SendResult

Validate, merge context, build MIME, and transmit.

Never raises: every failure — an invalid message, an unreadable attachment, a transport error — returns a failed :class:SendResult with the exception string + class name for structured logging.