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`` resourceThe 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 = statusGraphProvider
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 = graphlogger
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]) -> strTranslate 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