Skip to content

common_reports.emails.providers.smtp

SmtpProvider — the stdlib SMTP send + IMAP read backend (no extra deps).

Send (smtplib): connect (SMTPS on 465) -> (STARTTLS) -> login -> send_message(to_addrs=…) -> quit Read (imaplib): connect -> login -> select(folder) -> UID SEARCH -> UID FETCH BODY.PEEK[] -> parse

Reads use stable UIDs (not session sequence numbers) and BODY.PEEK[] so monitoring a mailbox never marks its messages as read. Message ids from a folder other than INBOX are "<folder>::<uid>" so a later get finds them.

This is the cleaned, reusable version of AlgoReports’ reporter.generate_email transport tail (send_message(msg, to_addrs=recipients); server.quit()), with the titan endpoint (smtp.titan.email:587 STARTTLS) as the default. The password comes from the :class:SmtpConfig (env-sourced :class:SecretStr) — never hardcoded.

Classes

SmtpProvider

Bases: BaseProvider

SMTP-send + optional IMAP-read backend (stdlib only).

Default endpoint = titan (smtp.titan.email:587 STARTTLS). Pass an :class:ImapConfig to enable :meth:list; without one the provider is send-only and list raises.

__init__

def __init__(smtp: SmtpConfig, imap: Optional[ImapConfig] = None)

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

backend

backend = 'smtp'

capabilities

capabilities = frozenset({EmailCapability.SEND})

imap

imap = imap

logger

logger = structlog.get_logger(self.__class__.__name__).bind(backend=(self.backend), host=(smtp.host))

smtp

smtp = smtp

get_attachment

def get_attachment(message_id: str, attachment_id: str) -> tuple[EmailAttachmentRecord, bytes]

get_backend_info

def get_backend_info() -> Mapping[str, Any]

get_message

def get_message(message_id: str) -> EmailMessageRecord

list

def list(folder: str = 'INBOX', limit: int = 10, unseen_only: bool = False) -> builtins.list[ReadResult]

imaplib: connect -> login -> select -> search -> fetch -> parse.

def search(query: MessageQuery) -> tuple[builtins.list[EmailMessageRecord], str | None, int | None]

send

def send(mime: Message, recipients: list[str]) -> str

smtplib: SMTP[_SSL](host, port) -> (starttls) -> login -> send_message -> quit.

Not retried: SMTP submission is not idempotent, and a resend after an ambiguous failure could deliver twice.