Skip to content

common_reports.emails.providers.graph

GraphProvider — Microsoft 365 / Exchange Online send via the Microsoft Graph API.

App-only OAuth2 (client-credentials), implemented with stdlib only (urllib + json — no msal, no requests, no new dependency):

token: POST {authority}/{tenant}/oauth2/v2.0/token (client_id + secret)
-> short-lived bearer token (cached in-process for its lifetime)
send: POST {graph}/users/{sender}/sendMail
Content-Type: application/json — a Graph ``message`` resource

The engine’s MIME message is translated into Graph’s JSON message so recipient roles survive exactly: visible To/Cc headers become toRecipients / ccRecipients; every other recipient is a bccRecipient (private delivery, the composer default — Bcc is never exposed). The HTML body (plus any trailing note parts), a plain-text-only body, file attachments and inline cid: images map to the message body and fileAttachment resources; custom X- headers ride internetMessageHeaders (the only custom headers Graph accepts).

Throttling (429) and unavailability (503/504) are retried up to GraphConfig.max_retries honoring Retry-After; other failures are NOT retried — a sendMail is not idempotent. Attachments above Graph’s ~3 MB inline request limit fail closed (upload sessions are not implemented). Secrets come from the :class:GraphConfig (env-sourced SecretStr) — never hardcoded.

Send-only: list() raises (read via the Gmail API or an IMAP provider).

Classes

GraphError

Bases: RuntimeError

A Microsoft Graph token or send failure, with the HTTP status when known.

__init__

def __init__(message: str, status: Optional[int] = None)

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

status

status = status

GraphProvider

Bases: BaseProvider

Microsoft Graph send backend — app-only OAuth2, JSON message (stdlib only).

__init__

def __init__(graph: GraphConfig, *, sleep: Callable[[float], None] = time.sleep)

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

backend

backend = 'graph'

capabilities

capabilities = frozenset({EmailCapability.SEND})

graph

graph = graph

logger

logger = structlog.get_logger(self.__class__.__name__).bind(backend=(self.backend), sender=(graph.sender))

get_backend_info

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

graph_message

def graph_message(mime: Message, recipients: list[str]) -> dict[str, Any]

The Graph message resource for a built MIME message (no I/O).

list

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

Not supported — the Graph backend here is send-only.

send

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

Translate the MIME message to a Graph message and POST it to sendMail.

Types and values

GRAPH_MAX_INLINE_ATTACHMENT_BYTES

GRAPH_MAX_INLINE_ATTACHMENT_BYTES = 3 * 1024 * 1024