What Is the Microsoft Graph Mail API? A Plain Explanation

When you install an email app that works with Microsoft 365 or Outlook.com, a consent screen appears before the connection completes. It lists a set of permissions — Mail.Read, Mail.ReadWrite, Mail.Send — and asks whether you agree to grant them. Most people click through. The Microsoft Graph mail API is the mechanism behind that screen: the REST interface that enforces exactly what an approved app can and cannot do with your mailbox.

Understanding it answers a practical question every person using an Outlook-connected app faces: what have you actually agreed to let that app do? This article explains the API, its permission model, how incremental sync and change notifications work, and how it compares to the older IMAP approach for Outlook.

What is the Microsoft Graph mail API?#

The Microsoft Graph mail API is the REST interface Microsoft provides for reading, writing, and sending email in Microsoft 365 and Outlook.com mailboxes. Apps authenticate with OAuth 2.0 through Microsoft Entra ID, receive a scoped access token, and make HTTPS requests to endpoints under graph.microsoft.com to interact with messages, folders, and attachments.

It is one part of the broader Microsoft Graph platform — Microsoft's single REST gateway for Microsoft 365 services, including calendar, contacts, files, Teams, and SharePoint. The mail resources sit under /me/messages (the default inbox), /me/mailFolders (folder list and management), and /me/sendMail (outbound sending). Attachments, categories, and inbox rules each have their own sub-resources under those paths.

Microsoft Graph replaced the older Exchange Web Services (EWS) API, which used SOAP and was significantly more complex to integrate. Microsoft's stated direction is Graph as the modern path for all new integrations; anything built today against Outlook mail uses Graph. Apps still on EWS face an extended but finite deprecation window.

How does the OAuth 2.0 authentication flow work?#

An app does not get direct access to your mailbox. It first registers with Microsoft Entra ID, receives a client ID, and declares which permission scopes it needs. When you connect your account, Microsoft redirects you to a login page where those scopes are listed — this is the consent moment, and you control what you approve.

If you agree, Microsoft issues an authorization code that the app exchanges for a short-lived access token and, if the app requested the offline_access scope, a long-lived refresh token. The access token is what the app presents on every Graph API call; it expires in roughly one hour. The refresh token lets the app obtain a new access token in the background without prompting you to sign in again — which is how email clients stay connected and sync continuously.

You can revoke an app's access at any time from the Microsoft My Account page under Privacy, then App permissions. Revocation invalidates every token that app holds immediately. The next API call the app makes returns a 401 Unauthorized, and it loses all access to your mailbox from that moment forward.

What does each Mail permission scope actually allow?#

Permission scopes are granular and additive. An app can only do what the scopes it requested — and you approved — permit. Approving Mail.ReadWrite does not also grant Mail.Send; both must be requested explicitly. The table below shows the five mail-related scopes most commonly seen on consent screens and what each one opens and closes.

If an app asks for Mail.ReadWrite but not Mail.Send, the API will reject any send attempt with a 403 Forbidden. The narrower the scopes you approve, the narrower the surface of your mailbox that app can touch.

Microsoft Graph vs IMAP for Outlook — which approach do apps use?#

IMAP is a standard protocol that works across almost any mail server. Microsoft Graph is a proprietary REST API that works only with Microsoft 365 and Outlook.com. The two are not interchangeable: IMAP gives you the messages; Graph gives you the messages plus the rest of the Microsoft 365 platform, with a sync model that scales to large mailboxes far better.

For a generic email client that must support Gmail, Yahoo, and Outlook from the same codebase, IMAP remains the common denominator. For a Microsoft-focused app that needs delta sync, change notifications, or calendar and contacts access in the same authenticated session, Graph is the only path. Microsoft disabled basic authentication over IMAP for Microsoft 365 in October 2022, so even apps using IMAP for Outlook must now use OAuth 2.0 — the credential model has converged, even if the protocol has not.

How do delta queries and change notifications work?#

Two Graph features matter most for email apps that need to stay current without hammering the API on every tick: delta queries and change notifications.

A delta query — GET /me/messages/delta — returns every message that has changed since the last sync. On the first call it returns all messages plus a deltaLink token. On every subsequent call the app presents that token and receives only the additions, modifications, and deletions since then. An inbox with tens of thousands of messages becomes a small list of changes on each poll rather than a full re-download. The API handles the bookkeeping; the app stores only the token.

Change notifications go further: instead of the app polling on a schedule, it registers a subscription with an HTTPS endpoint. When a message arrives, is modified, or is deleted, Microsoft posts a notification to that endpoint within seconds. Combined with delta queries — the webhook wakes the app, the delta query fetches what changed — this is how modern email clients achieve real-time sync at low API cost. Subscriptions expire after a few days and must be renewed, but are otherwise low-maintenance.

Common misconceptions about Microsoft Graph permissions#

The consent screen compresses a technical permission model into a few lines of plain language, which creates predictable misreadings. Five come up most often.

• Mail.ReadWrite lets the app send email. It does not. Sending requires the separate Mail.Send scope. An app holding only Mail.ReadWrite can read, move, and delete messages but the API will reject any send attempt with a 403 Forbidden.
• The API stores copies of your email on the app's servers. It does not. Microsoft Graph proxies requests to Microsoft's servers, where your data lives. Whether the app persists what it reads is a question for that app's privacy policy, not for the API.
• Revoking access also deletes the app's local data. It does not. Revocation removes API access, but any messages already downloaded and stored by the app remain there. Check the app's data deletion policy separately if this matters to you.
• offline_access lets the app read your email when you are offline. It does not. offline_access enables the app to get a refresh token and renew its access silently. The app still needs a live connection to Microsoft's servers to read or send anything.
• All apps requesting Mail.ReadWrite are equally risky. Not quite. Scope is one input; the app's architecture, privacy model, and data-handling practices are others. Mail.ReadWrite from a reputable, independently audited service is not the same risk profile as Mail.ReadWrite from an unreviewed app.

How this shows up in AI Emaily#

AI Emaily connects to Microsoft 365 and Outlook.com using exactly the Microsoft Graph mail API mechanics described above — OAuth 2.0 through Microsoft Entra ID, scoped to the permissions the features you use require, with delta sync and change notifications for real-time inbox updates. Because the product includes an autonomous AI agent that triages, drafts, and manages your inbox, it requests Mail.ReadWrite and Mail.Send — the scopes needed to act on messages and send replies on your behalf. Every send waits for your explicit approval before it leaves; the agent never dispatches mail silently. We build AI Emaily.

The architecture keeps you in control throughout: you can revoke access from the Microsoft My Account page at any moment, the agent treats incoming email as data to act on rather than instructions to obey, and every action it takes is captured in a reviewable audit trail. If you use Outlook and want to see how Graph API's permission model translates into a live, approve-before-send workflow, you can connect your account and try AI Emaily free for 7 days — see aiemaily.com/pricing for plans.