Microsoft 365 Graph API: mail, calendar, Teams, and SharePoint as AI source

What is the Microsoft Graph API?

The Microsoft Graph API is the unified REST interface through which all Microsoft 365 services can be addressed programmatically: Outlook mail, calendar, Teams, OneDrive, SharePoint, Entra ID (formerly Azure AD), Planner, To-Do, Excel, Word, OneNote. In recent years it has replaced the older EWS (Exchange Web Services) and SharePoint CSOM interfaces and has been the recommended path for Microsoft 365 integrations since around 2020.

The base URL is https://graph.microsoft.com/v1.0. Alongside there is a /beta endpoint that offers newer features but without stability guarantee. The API speaks JSON, uses OData v4 for filtering and pagination, and supports both delegated permissions (user is logged in) and application permissions (background service without user).

For AI workflows in fiduciary and law firms the most important endpoints are: /me/messages or /users/{id}/messages (mails), /me/events (calendar events), /me/drive/items (OneDrive files), /sites/{id}/lists/{id}/items (SharePoint lists), /teams/{id}/channels/{id}/messages (Teams chats). As of May 2026 the throttling limits are transparent in the docs: around 10,000 requests per 10 minutes per app and tenant for mail operations, higher for read-only operations on directory data.

Change Notifications (Graph webhooks) allow subscriptions on resources: you are notified as soon as a new mail arrives, an event changes, or a SharePoint file is updated. The subscription is limited to a maximum of 3 days and must be renewed.

Why it matters for Swiss fiduciary

In Swiss fiduciary and law firms, Microsoft 365 (Business Standard or Business Premium) is the dominant office stack, with an estimated 80 to 90 percent market share. Client correspondence runs through Outlook, appointments through the Outlook calendar, documents sit in OneDrive or SharePoint, Teams is the tool for internal communication. Without a connection to Graph the AI lacks access to daily work.

Three AI use-cases have the highest ROI. First: mail triage. Incoming mails are automatically classified (client inquiry, tax office notice, vendor invoice, spam), assigned to the right case handler, and accompanied by a first-reply proposal. With a 5-person firm and 200 mails per day, you save 2 to 3 hours per day.

Second: appointment preparation. Before each client meeting the AI generates a short briefing note: last 5 emails, open items, ToDos from previous sessions, current bookkeeping situation. The fiduciary receives the note 30 minutes before the appointment in Outlook.

Third: document indexing. SharePoint and OneDrive documents are continuously indexed in a vector DB. Client questions can be answered via RAG with source citations: "What compensation arrangement did we have in 2024 for this client?" and the LLM cites the exact contract from SharePoint.

How it works

Entry happens in four steps: register the app in Entra ID, select permissions, get a token, query endpoints.

App registration happens in the Entra Admin Center (Azure portal). You receive an application (client) ID and a directory (tenant) ID. For background services you additionally create a client secret or a certificate. In the API permissions area you choose the required Microsoft Graph permissions, e.g. Mail.Read for read access to mails, Files.Read.All for read access to all SharePoint files. Application permissions must be approved by the tenant admin via admin consent.

The OAuth flow for background services uses the client-credentials flow:

```bash curl -X POST "https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/token" \ -d "client_id=$CLIENT_ID" \ -d "scope=https://graph.microsoft.com/.default" \ -d "client_secret=$CLIENT_SECRET" \ -d "grant_type=client_credentials" ```

With the access token (valid 60 minutes) you then query the Graph endpoints:

```bash curl -X GET "https://graph.microsoft.com/v1.0/users/[email protected]/messages?\$top=10&\$select=subject,from,receivedDateTime" \ -H "Authorization: Bearer $ACCESS_TOKEN" ```

The response comes as an OData envelope with a value array and @odata.nextLink for pagination. On throttling (429), Graph returns a Retry-After header in seconds; you wait exactly that long before retrying.

For change notifications you create a subscription via POST /subscriptions with a notificationUrl of your receiving endpoint. Microsoft validates the URL through a one-time validation request; subsequently notifications run as JSON POSTs to your endpoint.

Graph integration in 5 steps

1. 01Register the app in Entra ID, define application permissions (Mail.Read, Files.Read.All, Calendars.Read).
2. 02Obtain admin consent from the tenant admin, store client secret or certificate safely in a secrets manager.
3. 03Implement the client-credentials flow, renew the access token every 60 minutes, retry logic with exponential backoff.
4. 04Build the read pipeline: fetch mails, events, and files via OData queries, incremental changes via the /delta endpoint.
5. 05Set up change notifications, renew the subscription every 2 days, secure the validation endpoint with HMAC check.

When to use

The Graph integration is the right choice when Microsoft 365 is the primary office tool and you want to embed AI workflows in daily work. The investment almost always pays off once at least three use cases are integrated in parallel.

Rough thresholds: mail triage pays off from around 80 mails per day per employee. Appointment preparation pays off from around 5 appointments per day in the firm. Document RAG pays off from around 5,000 indexed documents in SharePoint.

For hybrid mandates that sit partly on Microsoft 365 and partly on Google Workspace, you typically integrate both APIs (see Google Workspace Integration). The AI layer abstracts the source platform and answers uniformly.

When not to use

If the firm does not sit on Microsoft 365 but on a pure on-prem Exchange installation, Graph is not the right path. Here you must go via EWS (Exchange Web Services), which is a different API architecture and was marked as deprecated by Microsoft in 2024. A migration to Microsoft 365 is the economically better precondition here.

For very privacy-sensitive mandates (such as asset management with FINMA supervision or law mandates under extended professional secrecy), mail triage must either run locally in the Microsoft 365 tenant (with tenant-restricted permissions) or mails must be pseudonymised before AI analysis. A blind forward to an external LLM provider is not permissible here.

For pure read-once operations (such as a one-time export of all old mails) Graph is technically overkill; a PowerShell script or a PST file is enough.

Trade-offs

FAQ

Related topics

Sources

1. Microsoft Learn: Microsoft Graph REST API v1.0 reference · 2026-05
2. Microsoft Graph throttling guidance · 2026-04
3. Microsoft 365 Swiss data residency overview · 2026-05
4. Microsoft Graph change notifications · 2026-05