"""Microsoft Graph mailbox backend"""
from __future__ import annotations
import asyncio
import atexit
import logging
from collections.abc import Callable
from enum import Enum
from functools import lru_cache
from pathlib import Path
from time import sleep
from typing import Any, ClassVar
from mailsuite.mailbox.base import FolderNotFoundError, MailboxConnection
try:
from azure.identity import (
AuthenticationRecord,
CertificateCredential,
ClientAssertionCredential,
ClientSecretCredential,
DeviceCodeCredential,
TokenCachePersistenceOptions,
UsernamePasswordCredential,
)
from kiota_authentication_azure.azure_identity_authentication_provider import (
AzureIdentityAuthenticationProvider,
)
from msgraph.generated.models.body_type import BodyType
from msgraph.generated.models.email_address import EmailAddress
from msgraph.generated.models.file_attachment import FileAttachment
from msgraph.generated.models.item_body import ItemBody
from msgraph.generated.models.mail_folder import MailFolder
from msgraph.generated.models.message import Message
from msgraph.generated.models.recipient import Recipient
from msgraph.generated.users.item.mail_folders.item.child_folders.child_folders_request_builder import (
ChildFoldersRequestBuilder,
)
from msgraph.generated.users.item.mail_folders.item.messages.messages_request_builder import (
MessagesRequestBuilder,
)
from msgraph.generated.users.item.mail_folders.item.move.move_post_request_body import (
MovePostRequestBody as FolderMovePostRequestBody,
)
from msgraph.generated.users.item.mail_folders.mail_folders_request_builder import (
MailFoldersRequestBuilder,
)
from msgraph.generated.users.item.messages.item.move.move_post_request_body import (
MovePostRequestBody,
)
from msgraph.generated.users.item.send_mail.send_mail_post_request_body import (
SendMailPostRequestBody,
)
from msgraph.graph_request_adapter import GraphRequestAdapter
from msgraph.graph_service_client import GraphServiceClient
from msgraph_core import GraphClientFactory
except ImportError as e:
raise ImportError(
"MSGraphConnection requires the 'msgraph' extra: "
"pip install mailsuite[msgraph]"
) from e
logger = logging.getLogger(__name__)
[docs]
class AuthMethod(Enum):
DeviceCode = 1
UsernamePassword = 2
ClientSecret = 3
Certificate = 4
ClientAssertion = 5
DEFAULT_TOKEN_CACHE_NAME = "mailsuite"
def _get_cache_args(
token_path: Path,
allow_unencrypted_storage: bool,
cache_name: str = DEFAULT_TOKEN_CACHE_NAME,
) -> dict:
cache_args: dict = {
"cache_persistence_options": TokenCachePersistenceOptions(
name=cache_name, allow_unencrypted_storage=allow_unencrypted_storage
)
}
auth_record = _load_token(token_path)
if auth_record:
cache_args["authentication_record"] = AuthenticationRecord.deserialize(
auth_record
)
return cache_args
def _load_token(token_path: Path) -> str | None:
if not token_path.exists():
return None
with token_path.open() as token_file:
return token_file.read()
def _cache_auth_record(record: AuthenticationRecord, token_path: Path) -> None:
token = record.serialize()
token_path.parent.mkdir(parents=True, exist_ok=True)
with token_path.open("w") as token_file:
token_file.write(token)
def _generate_credential(auth_method: str, token_path: Path, **kwargs):
cache_name = kwargs.get("cache_name", DEFAULT_TOKEN_CACHE_NAME)
if auth_method == AuthMethod.DeviceCode.name:
return DeviceCodeCredential(
client_id=kwargs["client_id"],
disable_automatic_authentication=True,
tenant_id=kwargs["tenant_id"],
**_get_cache_args(
token_path,
allow_unencrypted_storage=kwargs["allow_unencrypted_storage"],
cache_name=cache_name,
),
)
if auth_method == AuthMethod.UsernamePassword.name:
return UsernamePasswordCredential(
client_id=kwargs["client_id"],
client_credential=kwargs["client_secret"],
disable_automatic_authentication=True,
username=kwargs["username"],
password=kwargs["password"],
**_get_cache_args(
token_path,
allow_unencrypted_storage=kwargs["allow_unencrypted_storage"],
cache_name=cache_name,
),
)
if auth_method == AuthMethod.ClientAssertion.name:
provider = kwargs.get("client_assertion_provider")
if provider is None:
raise ValueError(
"client_assertion or client_assertion_provider is required "
"when auth_method is 'ClientAssertion'"
)
return ClientAssertionCredential(
tenant_id=kwargs["tenant_id"],
client_id=kwargs["client_id"],
func=provider,
)
if auth_method == AuthMethod.ClientSecret.name:
return ClientSecretCredential(
client_id=kwargs["client_id"],
tenant_id=kwargs["tenant_id"],
client_secret=kwargs["client_secret"],
)
if auth_method == AuthMethod.Certificate.name:
cert_path = kwargs.get("certificate_path")
if not cert_path:
raise ValueError(
"certificate_path is required when auth_method is 'Certificate'"
)
return CertificateCredential(
client_id=kwargs["client_id"],
tenant_id=kwargs["tenant_id"],
certificate_path=cert_path,
password=kwargs.get("certificate_password"),
)
raise RuntimeError(f"Auth method {auth_method} not found")
_persistent_loop: asyncio.AbstractEventLoop | None = None
def _run(coro):
"""Run a coroutine to completion on a persistent event loop.
Refuses to nest in a running loop. We retain a single persistent
loop across calls because the Graph SDK's underlying
``httpx.AsyncClient`` keeps connection-pool resources bound to the
loop that issued the first request — closing the loop between calls
(as ``asyncio.run`` does) invalidates those resources and surfaces
on the next call as ``RuntimeError: Event loop is closed``. See
https://github.com/domainaware/parsedmarc/issues/742.
"""
global _persistent_loop
try:
asyncio.get_running_loop()
except RuntimeError:
pass
else:
raise RuntimeError(
"MSGraphConnection cannot be called from inside a running event loop. "
"Use msgraph.GraphServiceClient directly from async code."
)
if _persistent_loop is None or _persistent_loop.is_closed():
_persistent_loop = asyncio.new_event_loop()
asyncio.set_event_loop(_persistent_loop)
return _persistent_loop.run_until_complete(coro)
@atexit.register
def _close_persistent_loop() -> None:
global _persistent_loop
if _persistent_loop is not None and not _persistent_loop.is_closed():
_persistent_loop.close()
_persistent_loop = None
[docs]
class MSGraphConnection(MailboxConnection):
"""
A :class:`MailboxConnection` backed by Microsoft Graph
Supports DeviceCode, UsernamePassword, ClientSecret, ClientAssertion,
and Certificate auth via :mod:`azure.identity`. Send mail goes through
``/users/{mailbox}/sendMail`` with a structured ``Message`` body; the
request sets ``saveToSentItems``, so a copy is saved to Sent Items
by default. Pass ``save_to_sent_items=False`` to skip saving a copy.
Required Microsoft Graph **API permissions** on the app registration
(combine as needed):
* Read-only (``fetch_message``, ``fetch_messages``): ``Mail.Read``
* Read + modify (mark read, delete, move, create folder):
``Mail.ReadWrite``
* Send mail (``send_message``): ``Mail.Send``
Delegated flows (``DeviceCode``, ``UsernamePassword``) targeting a
shared mailbox (i.e. ``mailbox != username``) use the ``.Shared``
variants — ``Mail.Read.Shared``, ``Mail.ReadWrite.Shared``,
``Mail.Send.Shared``. App-only flows (``ClientSecret``,
``ClientAssertion``, ``Certificate``) do not need the ``.Shared``
variants. See the README "Microsoft Graph permissions" section for the
full mapping.
Note: delegated flows always request ``Mail.ReadWrite`` at
authenticate time, so even read-only callers must consent to at
least ``Mail.ReadWrite``.
Requires the ``msgraph`` extra::
pip install mailsuite[msgraph]
"""
_WELL_KNOWN_FOLDERS: ClassVar[dict[str, str]] = {
"inbox": "inbox",
"archive": "archive",
"drafts": "drafts",
"sentitems": "sentitems",
"deleteditems": "deleteditems",
"junkemail": "junkemail",
}
def __init__(
self,
auth_method: str,
mailbox: str,
client_id: str,
client_secret: str | None,
username: str | None,
password: str | None,
tenant_id: str,
token_file: str,
allow_unencrypted_storage: bool,
certificate_path: str | None = None,
certificate_password: str | bytes | None = None,
graph_url: str | None = None,
token_cache_name: str = DEFAULT_TOKEN_CACHE_NAME,
client_assertion: str | None = None,
client_assertion_provider: Callable[[], str] | None = None,
):
"""
Args:
auth_method: One of the names in :class:`AuthMethod`
mailbox: The mailbox UPN (e.g. ``user@example.com``)
client_id: Application (client) ID
client_secret: Client secret (required for ClientSecret auth)
username: User principal name (required for UsernamePassword auth)
password: Password (required for UsernamePassword auth)
tenant_id: Azure AD tenant ID
token_file: Path to the file used to persist the
``AuthenticationRecord`` between runs
allow_unencrypted_storage: Pass through to
:class:`azure.identity.TokenCachePersistenceOptions`
certificate_path: PEM/PFX path for Certificate auth
certificate_password: Optional password for the certificate
graph_url: Microsoft Graph endpoint URL. Defaults to the worldwide
cloud. Pass a sovereign cloud URL (e.g.
``"https://graph.microsoft.us"``) or any other Graph endpoint
to override.
token_cache_name: ``msal``/``azure-identity`` token cache name.
Defaults to ``"mailsuite"``. Downstream consumers migrating
from a previous installation can pass the old cache name
(e.g. ``"parsedmarc"``) so existing cached
``AuthenticationRecord``s and tokens continue to work.
client_assertion: A static client assertion for ClientAssertion
auth — a signed JWT (e.g. a federated credential) that
``azure-identity`` exchanges for an access token via the
JWT-bearer client-credentials grant, *not* a Graph access
token. For long-running connections prefer
``client_assertion_provider`` so a fresh assertion is
available when the credential needs a new token.
client_assertion_provider: A zero-arg callable returning a
current client assertion (signed JWT).
:class:`~azure.identity.ClientAssertionCredential` calls it
each time it acquires a new access token, so the callable is
responsible for returning a valid (unexpired) assertion.
"""
token_path = Path(token_file)
if client_assertion is not None and client_assertion_provider is None:
static_assertion = client_assertion
def _static_assertion_provider() -> str:
return static_assertion
client_assertion_provider = _static_assertion_provider
credential = _generate_credential(
auth_method,
client_id=client_id,
client_secret=client_secret,
certificate_path=certificate_path,
certificate_password=certificate_password,
username=username,
password=password,
tenant_id=tenant_id,
token_path=token_path,
allow_unencrypted_storage=allow_unencrypted_storage,
cache_name=token_cache_name,
client_assertion_provider=client_assertion_provider,
)
scopes: list[str] | None = None
if not isinstance(credential, (ClientAssertionCredential, ClientSecretCredential,
CertificateCredential)):
scopes = ["Mail.ReadWrite"]
# Detect if mailbox is shared
if mailbox and username and username != mailbox:
scopes = ["Mail.ReadWrite.Shared"]
auth_record = credential.authenticate(scopes=scopes)
_cache_auth_record(auth_record, token_path)
if graph_url is None:
self._client = GraphServiceClient(credentials=credential, scopes=scopes)
else:
httpx_client = GraphClientFactory.create_with_default_middleware()
httpx_client.base_url = f"{graph_url.rstrip('/')}/v1.0"
auth_provider = AzureIdentityAuthenticationProvider(
credentials=credential, scopes=scopes or []
)
adapter = GraphRequestAdapter(
auth_provider=auth_provider, client=httpx_client
)
self._client = GraphServiceClient(request_adapter=adapter)
self.mailbox_name = mailbox
# — folder management —
[docs]
def create_folder(self, folder_name: str) -> None:
path_parts = folder_name.split("/")
parent_folder_id: str | None = None
if len(path_parts) > 1:
for folder in path_parts[:-1]:
parent_folder_id = self._find_folder_id_with_parent(
folder, parent_folder_id
)
folder_name = path_parts[-1]
body = MailFolder(display_name=folder_name)
try:
if parent_folder_id is None:
_run(
self._client.users.by_user_id(
self.mailbox_name
).mail_folders.post(body)
)
else:
_run(
self._client.users.by_user_id(self.mailbox_name)
.mail_folders.by_mail_folder_id(parent_folder_id)
.child_folders.post(body)
)
logger.debug("Created folder %s", folder_name)
except Exception as e:
if getattr(e, "response_status_code", None) == 409:
logger.debug("Folder %s already exists, skipping", folder_name)
return
raise
[docs]
def rename_folder(self, old_name: str, new_name: str) -> None:
"""
Rename a mail folder in place
Issues ``PATCH /users/{mailbox}/mailFolders/{id}`` with a new
``displayName`` (requires ``Mail.ReadWrite``). Graph's update
operation only changes the folder's display name — it does *not*
move the folder to a different parent (relocating a folder is a
separate ``move`` action). Accordingly, only the leaf segment of
``new_name`` is used as the new display name, so passing a
``parent/child`` path won't create a folder whose name literally
contains a slash. The folder's id is unchanged by a rename.
Args:
old_name: The current folder name or ``parent/child`` path
new_name: The new display name (leaf segment is used)
Raises:
FolderExistsError: If ``new_name`` already resolves to a folder.
"""
self._ensure_no_folder_conflict(new_name)
folder_id = self._find_folder_id_from_folder_path(old_name)
display_name = new_name.split("/")[-1]
_run(
self._client.users.by_user_id(self.mailbox_name)
.mail_folders.by_mail_folder_id(folder_id)
.patch(MailFolder(display_name=display_name))
)
# The path→id cache now holds a stale name for this folder; the
# folder id itself is unchanged by a rename.
self._find_folder_id_from_folder_path.cache_clear()
[docs]
def folder_exists(self, folder_name: str) -> bool:
"""Return ``True`` if the folder (by name or ``parent/child`` path)
resolves to an id, ``False`` if no such folder exists. A failed
listing call (auth/network) propagates as ``RuntimeError`` rather than
being reported as a missing folder."""
try:
return bool(self._find_folder_id_from_folder_path(folder_name))
except FolderNotFoundError:
return False
[docs]
def delete_folder(self, folder_name: str) -> None:
folder_id = self._find_folder_id_from_folder_path(folder_name)
_run(
self._client.users.by_user_id(self.mailbox_name)
.mail_folders.by_mail_folder_id(folder_id)
.delete()
)
self._find_folder_id_from_folder_path.cache_clear()
def _do_move_folder(
self, source: str, target_parent: str, target_path: str
) -> None:
# Graph's native move action relocates the folder and its contents
# under a new parent (destinationId), preserving the display name.
# Moving can change the folder id, so use the id from the response for
# any follow-up rename. "" parent means the mailbox root.
folder_id = self._find_folder_id_from_folder_path(source)
if target_parent:
parent_id = self._find_folder_id_from_folder_path(target_parent)
else:
parent_id = "msgfolderroot"
moved = _run(
self._client.users.by_user_id(self.mailbox_name)
.mail_folders.by_mail_folder_id(folder_id)
.move.post(FolderMovePostRequestBody(destination_id=parent_id))
)
if moved is not None and moved.id:
folder_id = moved.id
# Full-path moves may also rename the leaf; the native move doesn't.
target_leaf = target_path.rpartition("/")[2]
if target_leaf != source.rpartition("/")[2]:
_run(
self._client.users.by_user_id(self.mailbox_name)
.mail_folders.by_mail_folder_id(folder_id)
.patch(MailFolder(display_name=target_leaf))
)
self._find_folder_id_from_folder_path.cache_clear()
# — message reading —
[docs]
def fetch_messages(self, reports_folder: str, **kwargs: Any) -> list[str]:
folder_id = self._find_folder_id_from_folder_path(reports_folder)
since = kwargs.get("since") or None
batch_size = kwargs.get("batch_size") or 0
return _run(self._fetch_messages_async(folder_id, batch_size, since))
async def _fetch_messages_async(
self, folder_id: str, batch_size: int, since: str | None
) -> list[str]:
query = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
select=["id"],
top=batch_size if batch_size > 0 else 100,
)
if since:
query.filter = f"receivedDateTime ge {since}"
config = (
MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
query_parameters=query
)
)
page = (
await self._client.users.by_user_id(self.mailbox_name)
.mail_folders.by_mail_folder_id(folder_id)
.messages.get(request_configuration=config)
)
ids: list[str] = []
while page is not None and page.value:
ids.extend(m.id for m in page.value if m.id)
next_link = page.odata_next_link
keep_going = batch_size == 0 or len(ids) < batch_size
if not next_link or not keep_going:
break
page = (
await self._client.users.by_user_id(self.mailbox_name)
.mail_folders.by_mail_folder_id(folder_id)
.messages.with_url(next_link)
.get()
)
return ids
[docs]
def fetch_message(self, message_id: Any, **kwargs: Any) -> str:
raw = _run(
self._client.users.by_user_id(self.mailbox_name)
.messages.by_message_id(str(message_id))
.content.get()
)
if kwargs.get("mark_read"):
self.mark_message_read(str(message_id))
if raw is None:
return ""
return bytes(raw).decode("utf-8", errors="replace")
[docs]
def mark_message_read(self, message_id: str) -> None:
"""Mark the message with the given id as read (Graph-only; not part
of the ``MailboxConnection`` interface)"""
_run(
self._client.users.by_user_id(self.mailbox_name)
.messages.by_message_id(message_id)
.patch(Message(is_read=True))
)
[docs]
def delete_message(self, message_id: Any) -> None:
_run(
self._client.users.by_user_id(self.mailbox_name)
.messages.by_message_id(str(message_id))
.delete()
)
[docs]
def move_message(self, message_id: Any, folder_name: str) -> None:
folder_id = self._find_folder_id_from_folder_path(folder_name)
body = MovePostRequestBody(destination_id=folder_id)
_run(
self._client.users.by_user_id(self.mailbox_name)
.messages.by_message_id(str(message_id))
.move.post(body)
)
[docs]
def keepalive(self) -> None:
# Graph uses bearer tokens; nothing to ping
return
[docs]
def watch(
self,
check_callback: Callable[[MailboxConnection], None],
check_timeout: int,
config_reloading: Callable[[], bool] | None = None,
) -> None:
"""Poll the mailbox at ``check_timeout``-second intervals"""
while True:
if config_reloading and config_reloading():
return
sleep(check_timeout)
if config_reloading and config_reloading():
return
check_callback(self)
# — sending —
[docs]
def send_message(
self,
message_from: str,
message_to: list[str] | None = None,
message_cc: list[str] | None = None,
message_bcc: list[str] | None = None,
subject: str | None = None,
message_headers: dict | None = None,
attachments: list[tuple[str, bytes]] | None = None,
plain_message: str | None = None,
html_message: str | None = None,
save_to_sent_items: bool = True,
) -> str | None:
# Graph derives ``From`` from the authenticated mailbox; ``message_from``
# and ``message_headers`` are accepted for API parity but not used by
# the structured /sendMail endpoint.
del message_from, message_headers
if html_message is not None:
body = ItemBody(content_type=BodyType.Html, content=html_message)
else:
body = ItemBody(content_type=BodyType.Text, content=plain_message or "")
def _to_recipients(addrs: list[str] | None) -> list[Recipient] | None:
if not addrs:
return None
return [
Recipient(email_address=EmailAddress(address=addr)) for addr in addrs
]
graph_attachments: list[Any] | None = None
if attachments:
graph_attachments = [
FileAttachment(
odata_type="#microsoft.graph.fileAttachment",
name=filename,
content_bytes=payload,
)
for filename, payload in attachments
]
message = Message(
subject=subject,
body=body,
to_recipients=_to_recipients(message_to),
cc_recipients=_to_recipients(message_cc),
bcc_recipients=_to_recipients(message_bcc),
attachments=graph_attachments,
)
request = SendMailPostRequestBody(
message=message, save_to_sent_items=save_to_sent_items
)
_run(
self._client.users.by_user_id(self.mailbox_name).send_mail.post(request)
)
return None
# — folder ID resolution —
@lru_cache(maxsize=10) # noqa: B019
def _find_folder_id_from_folder_path(self, folder_name: str) -> str:
path_parts = folder_name.split("/")
parent_folder_id: str | None = None
if len(path_parts) > 1:
for folder in path_parts[:-1]:
parent_folder_id = self._find_folder_id_with_parent(
folder, parent_folder_id
)
return self._find_folder_id_with_parent(path_parts[-1], parent_folder_id)
return self._find_folder_id_with_parent(folder_name, None)
def _get_well_known_folder_id(self, folder_name: str) -> str | None:
folder_key = folder_name.lower().replace(" ", "").replace("-", "")
alias = self._WELL_KNOWN_FOLDERS.get(folder_key)
if alias is None:
return None
try:
folder = _run(
self._client.users.by_user_id(self.mailbox_name)
.mail_folders.by_mail_folder_id(alias)
.get()
)
except Exception: # noqa: BLE001
return None
return folder.id if folder else None
def _find_folder_id_with_parent(
self, folder_name: str, parent_folder_id: str | None
) -> str:
try:
folders = self._list_folders_filtered(folder_name, parent_folder_id)
except Exception as e:
if parent_folder_id is None:
well_known = self._get_well_known_folder_id(folder_name)
if well_known:
return well_known
raise RuntimeError(f"Failed to list folders: {e}") from e
for folder in folders:
if folder.display_name == folder_name and folder.id:
return folder.id
if parent_folder_id is None:
well_known = self._get_well_known_folder_id(folder_name)
if well_known:
return well_known
# Distinct type from the "Failed to list folders" RuntimeError above,
# so folder_exists can treat a genuine miss as False while letting
# listing failures (auth/network) propagate.
raise FolderNotFoundError(f"folder {folder_name} not found")
def _list_folders_filtered(
self, folder_name: str, parent_folder_id: str | None
) -> list[MailFolder]:
# OData string-literal escape: single quotes are doubled.
escaped = folder_name.replace("'", "''")
if parent_folder_id is None:
query = MailFoldersRequestBuilder.MailFoldersRequestBuilderGetQueryParameters(
filter=f"displayName eq '{escaped}'"
)
config = MailFoldersRequestBuilder.MailFoldersRequestBuilderGetRequestConfiguration(
query_parameters=query
)
page = _run(
self._client.users.by_user_id(
self.mailbox_name
).mail_folders.get(request_configuration=config)
)
else:
child_query = ChildFoldersRequestBuilder.ChildFoldersRequestBuilderGetQueryParameters(
filter=f"displayName eq '{escaped}'"
)
child_config = ChildFoldersRequestBuilder.ChildFoldersRequestBuilderGetRequestConfiguration(
query_parameters=child_query
)
page = _run(
self._client.users.by_user_id(self.mailbox_name)
.mail_folders.by_mail_folder_id(parent_folder_id)
.child_folders.get(request_configuration=child_config)
)
return list(page.value or []) if page is not None else []