Skip to content

common_reports.emails.providers.base

Provider effect boundary and explicit mailbox capability contract.

Classes

BaseProvider

Bases: ABC

Abstract email backend adapter: effects and SDK translation only.

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

backend

backend: str = 'base'

capabilities

capabilities: frozenset[EmailCapability] = frozenset()

close

def close() -> None

Release what the provider holds between calls. A provider that opens nothing that outlives a call keeps this default.

create_draft

def create_draft(mime: Message, thread_id: str | None, recipients: builtins.list[str] | None = None) -> Mapping[str, Any]

create_label

def create_label(request: LabelCreateRequest) -> EmailLabelRecord

delete_draft

def delete_draft(draft_id: str) -> None

delete_label

def delete_label(label_id: str) -> None

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

get_profile

def get_profile() -> MailboxProfile

get_thread

def get_thread(thread_id: str) -> EmailThreadRecord

header_routed

@staticmethod
def header_routed(mime: Message, recipients: builtins.list[str]) -> Message

A copy of mime whose headers name every recipient, for APIs that deliver by the MIME headers (Gmail) instead of an SMTP envelope.

Recipients not already in a visible To/Cc header are added as Bcc — the API delivers to them and strips the header, so private delivery (the composer default) stays private. The caller’s message is never mutated.

list

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

Compatibility list operation, newest first.

list_history

def list_history(query: HistoryQuery) -> tuple[str | None, builtins.list[EmailHistoryChange], str | None]

list_labels

def list_labels() -> builtins.list[EmailLabelRecord]

list_message_refs

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

One page of the messages a search matches, by identity, nothing fetched.

list_thread_refs

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

One page of the threads a search matches, by identity, nothing fetched.

modify_labels

def modify_labels(update: LabelUpdate) -> Mapping[str, Any]

reply

def reply(mime: Message, recipients: builtins.list[str], thread_id: str | None) -> str | EmailDeliveryRecord

require

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

send

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

Put a fully-built MIME message on the wire and return its id.

send_draft

def send_draft(draft_id: str) -> Mapping[str, Any]

stop_watch

def stop_watch() -> None

supports

def supports(capability: EmailCapability) -> bool

watch

def watch(request: WatchRequest) -> tuple[str | None, datetime | None]

HistoryExpiredError

Bases: LookupError

The history cursor is older than the mailbox keeps: resynchronize in full.

Gmail keeps history for at least a week, often longer, and answers an older or invalid start cursor with 404. Nothing was read; no later cursor exists.

__init__

def __init__(start_history_id: str)

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

start_history_id

start_history_id = start_history_id

UnsupportedEmailCapabilityError

Bases: RuntimeError

Raised before I/O when a provider cannot perform an operation.

__init__

def __init__(backend: str, capability: EmailCapability)

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

backend

backend = backend

capability

capability = capability