feat: add Microsoft 365 Graph mail source

docs/index.md

@@ -13,7 +13,7 @@ DMARQ is a full-stack DMARC monitoring platform designed to help organizations t
 - **DMARC Report Processing**: Automatically collect and parse DMARC aggregate and forensic reports
 - **Interactive Dashboard**: Visualize compliance rates and authentication trends
 - **DNS Health Checks**: Verify your email authentication records (SPF, DKIM, DMARC)
-- **IMAP Integration**: Automatically fetch reports from your email inbox
+- **Mailbox Integrations**: Automatically fetch reports from IMAP, Gmail, and Microsoft 365 inboxes
 - **Alerting**: Get notified about important authentication issues
 - **Easy Setup**: Web-based configuration wizard for quick onboarding
 
@@ -23,4 +23,6 @@ To get started with DMARQ, please see the [Getting Started](user_guide/getting_s
 
 For installation instructions, check the [Docker Setup](deployment/docker.md) or [Manual Installation](deployment/manual.md) guides. Operators should use the [Operator Runbook](deployment/operations.md) for deployment modes, verification, upgrades, and rollback, and the [Troubleshooting Playbooks](deployment/troubleshooting.md) for ingestion, authentication, DNS, database, and notification failures. For production secrets, use [Secret Handling with 1Password](deployment/secrets.md). For database operations, use [Database Backup and Restore](deployment/backups.md). For upgrades, use the [Release Checklist](deployment/release-checklist.md).
 
+For Microsoft 365 setup, see [Microsoft 365 Mail Sources](user_guide/microsoft365.md).
+
 For aggregate-report parser support, known edge cases, and fixture guidance, see [DMARC Aggregate Format Compatibility](reference/dmarc-compatibility.md).

docs/milestones.md

@@ -198,14 +198,14 @@ Exit criteria:
 
 ## Milestone 12: Enterprise Mail Sources (Microsoft 365) and Connector Framework
 
-Status: Planned
+Status: In progress
 
 Goal: make mailbox ingestion work for the most common enterprise setups without relying on IMAP.
 
 Planned:
-- Microsoft 365 mail source using OAuth (Graph) with least-privilege scopes.
+- Microsoft 365 mail source using OAuth (Graph) with least-privilege scopes. Delivered for delegated `User.Read`, `Mail.Read`, and `offline_access` with encrypted token storage, manual import, scheduled polling, UI setup, and operator docs.
 - Shared mailbox and folder selection support for DMARC report collection.
-- Import-history parity with existing sources (auditable attachment outcomes, duplicates, parse failures).
+- Import-history parity with existing sources (auditable attachment outcomes, duplicates, parse failures). Delivered for Microsoft 365 imports.
 - Backfill support with safe throttling and progressive search windows.
 - Secret handling mirrors existing guidance (no raw secrets in logs; 1Password-friendly).
 

docs/user_guide/microsoft365.md

@@ -0,0 +1,40 @@
+# Microsoft 365 Mail Sources
+
+DMARQ can import DMARC aggregate report attachments from Exchange Online through Microsoft Graph. Use this source type when IMAP is disabled or unavailable in a Microsoft 365 tenant.
+
+## App Registration
+
+Create an app registration in Microsoft Entra admin center:
+
+- Platform: Web
+- Redirect URI: `https://<your-dmarq-host>/api/v1/mail-sources/<source-id>/m365/callback`
+- Delegated API permissions:
+  - `User.Read`
+  - `Mail.Read`
+  - `offline_access`
+- Client secret: create a secret for the web app and store it in your deployment secret manager.
+
+`Mail.Read` is the least-privilege delegated Graph permission DMARQ needs to list messages and read file attachments. `offline_access` is requested so Microsoft returns a refresh token for scheduled polling.
+
+## DMARQ Setup
+
+1. Open **Mail Sources**.
+2. Add a source with method **Microsoft 365 (Graph OAuth2)**.
+3. Enter the tenant ID (`organizations`, `common`, or a tenant GUID), client ID, and client secret.
+4. Leave **Mailbox** empty to read the authorised account, or enter a user principal name for a shared/delegated mailbox that the authorised user can read.
+5. Save the source.
+6. Use **Connect Microsoft 365** and approve the read-only mailbox access request.
+7. Run **Test connection** and **Run import now**.
+
+## Import Behavior
+
+DMARQ reads recent messages in the configured folder, filters for messages that look like DMARC reports, downloads Graph `fileAttachment` items, and sends `.xml`, `.zip`, `.gz`, and `.gzip` attachments through the same parser and persistence path used by upload, IMAP, and Gmail imports.
+
+Imported Graph message IDs are stored on the mail source so scheduled polling does not reprocess the same message. Import history records processed messages, imported reports, duplicates, parse failures, and attachment-level details.
+
+## Troubleshooting
+
+- **Not authorised**: reconnect the source from Mail Sources.
+- **Permission error**: confirm the app registration has delegated `Mail.Read` and the authorised account can read the target mailbox.
+- **Throttling**: wait and retry, or increase the polling interval.
+- **Mailbox/folder not found**: leave Mailbox blank for `/me`, use a valid user principal name for delegated/shared mailboxes, and keep the default `INBOX` folder unless reports are delivered elsewhere.