The Outlook API, Microsoft's API for Outlook email and calendar, is Microsoft Graph today. Microsoft deprecated the old Outlook REST API, at outlook.office.com/api, and decommissioned it in March 2024. Exchange Web Services is being switched off in Exchange Online, from 1 October 2026 for tenants still on the default setting, with a final shutdown planned for 1 April 2027. Everything an app does with an Outlook or Microsoft 365 mailbox, reading, searching, sending, replying, syncing, getting webhooks, and managing the calendar, now goes through graph.microsoft.com, with an OAuth token from Microsoft Entra ID. The same API works for work accounts and for personal Outlook.com accounts.
This guide covers the setup, the permissions, mail and calendar calls in Python, change notifications and the failures that show up in production, from Microsoft Learn as read in November 2026. Sending limits and throttling have their own guide: Outlook sending limits.
Which Outlook API should you use?
There are four APIs with Outlook in the name, and only one is right for a new integration:
| API | Status in 2026 | Use it for |
|---|---|---|
| Microsoft Graph (graph.microsoft.com) | Current, the API Microsoft points everyone to | Mail, calendar and contacts for Microsoft 365 and Outlook.com |
| Outlook REST API v2.0 (outlook.office.com/api) | Decommissioned in March 2024 | Nothing; migrate to Graph, the resources are the same |
| Exchange Web Services (EWS) | Being switched off in Exchange Online from 1 October 2026, final shutdown planned for 1 April 2027 | Nothing new in the cloud |
| Office JavaScript API (Office.js) | Current | Add-ins that run inside the Outlook client, not server integrations |
Moving from the old Outlook REST endpoint is mostly mechanical: Microsoft's comparison page says Graph v1.0 matches Outlook v2.0, the permissions are the same, and properties go from PascalCase to camelCase. IMAP and SMTP with OAuth still exist for Microsoft 365, and our Outlook sending limits guide covers SMTP AUTH, but Graph is the only route that gives you webhooks, delta sync and the calendar in one API.
How do you set up the Outlook API?
Four steps in the Microsoft Entra admin center:
- Register an app under App registrations. Choose who can sign in: accounts in your organization only, any organization, or any organization plus personal Microsoft accounts if Outlook.com users must connect.
- Add a redirect URI for the sign-in flow, a web URL for a server app or a native URI for a desktop script.
- Add Microsoft Graph permissions, the narrowest that work, as below.
- Get tokens with MSAL, Microsoft's authentication library, which exists for Python, Node.js, .NET and Java. Your code then sends
Authorization: Bearer <token>to graph.microsoft.com.
Microsoft's mail API overview lists every Outlook mail resource and method. There is no API key for Outlook data: every call carries an OAuth access token, issued for a user who consented or for the app itself with an administrator's consent.
Which permissions does the Outlook API need?
Graph has two kinds of permission, and the choice decides who has to approve your app:
| Delegated permissions | Application permissions | |
|---|---|---|
| Who the app acts as | The signed-in user | Itself, with no user present |
| Who can consent | The user for their own data, or an admin for everyone, depending on the tenant's consent policy | Only an administrator |
| What it can reach | Only what that user can reach | Every mailbox the permission covers in the tenant |
| Personal Outlook.com accounts | Supported | Not supported |
For mail, the usual permissions are Mail.ReadBasic, Mail.Read, Mail.ReadWrite and Mail.Send, and for the calendar Calendars.Read and Calendars.ReadWrite. Microsoft's own guidance is to prefer delegated permissions whenever they do the job, because an application permission such as Mail.Send lets the app send as any user in the tenant. When an app does need application permissions, Exchange Online's RBAC for Applications is the way to limit which mailboxes it can touch.
How do you read and reply to emails with the Outlook API?
A list call takes OData parameters to filter and trim the response, and a reply call keeps the conversation together without any headers to build by hand. This Python example reads unread messages in the inbox and answers the first one:
import requests
GRAPH = "https://graph.microsoft.com/v1.0"
headers = {"Authorization": f"Bearer {token}"} # delegated token from MSAL: Mail.Read and Mail.Send
r = requests.get(
f"{GRAPH}/me/mailFolders/inbox/messages",
headers=headers,
params={
"$filter": "isRead eq false",
"$select": "id,subject,from,receivedDateTime,conversationId",
"$top": "25",
},
timeout=30,
)
r.raise_for_status()
messages = r.json()["value"]
for msg in messages:
print(msg["receivedDateTime"], msg["from"]["emailAddress"]["address"], msg["subject"])
if messages:
requests.post(
f"{GRAPH}/me/messages/{messages[0]['id']}/reply",
headers=headers,
json={"comment": "Thanks, following up on this."},
timeout=30,
).raise_for_status() # 202 Accepted; the reply is saved in Sent Items$select matters more than it looks: without it, every message comes back with its full body. Results arrive in pages, with an @odata.nextLink URL for the next one. The reply endpoint goes to the replyTo address when the original message has one, and createReply makes a draft instead when a person should check the text before it goes. To send a new email rather than a reply, the call is POST /me/sendMail, shown with retry handling in our Outlook sending limits guide. In both cases a 202 only means Exchange accepted the request: a bounce comes back later as a non-delivery report in the inbox, not as an API error.
How do you sync a mailbox with the Outlook API?
With delta queries. GET /me/mailFolders/{id}/messages/delta returns the messages in one folder, then an @odata.deltaLink URL; calling that URL later returns only what was added, changed or deleted since. Three rules from Microsoft's reference shape the code:
- Delta works per folder. Syncing a whole mailbox means one delta loop per folder you care about, usually the inbox and Sent Items.
- Filters are limited. The only
$filterdelta accepts is on receivedDateTime, the only$orderbyis receivedDateTime descending, and$searchis not supported. - Expect events you did not ask for. Delta returns read and unread changes and
@removedentries for messages deleted or moved out of the folder, even when they do not match your filter.
Store the deltaLink per folder and per mailbox, and treat it as the bookmark of your sync. For one-off lookups, the list call accepts $search with keywords such as from: and subject:, which delta does not.
How do you get new Outlook emails in real time?
With change notifications, Graph's webhooks. You create a subscription on a mailbox resource, and Graph calls your HTTPS endpoint when a message arrives:
POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json
{
"changeType": "created",
"notificationUrl": "https://example.com/graph/notifications",
"lifecycleNotificationUrl": "https://example.com/graph/lifecycle",
"resource": "/me/mailFolders('inbox')/messages",
"expirationDateTime": "2026-11-20T09:00:00Z",
"clientState": "a-secret-only-your-app-knows"
}Before the subscription exists, Graph sends a POST to your URL with a validationToken query parameter, and your endpoint must answer within 10 seconds with 200 OK, text/plain, and the decoded token as the body. Each notification then carries your clientState, which you check to reject anything Microsoft did not send, and the message id, which you fetch. Microsoft gives an average latency under a minute for messages and a maximum of three.
The lifetime is the trap. A subscription to Outlook messages, events or contacts lasts at most 10,080 minutes, just under 7 days, or 1,440 minutes when it includes resource data, so a renewal job is part of the integration, not an afterthought. Lifecycle notifications warn you before a subscription or its access token expires, and when an administrator revokes the app's access.
How do you use the Outlook calendar API?
The same way, on the event resources. GET /me/calendarView with a startDateTime and an endDateTime returns the events in that window, recurring meetings expanded into their occurrences, which is what a scheduling feature usually needs. POST /me/events creates an event and sends invitations to its attendees. Reading needs Calendars.Read, writing Calendars.ReadWrite, and calendar events support the same subscriptions as messages, with the same 10,080-minute lifetime.
What does the Outlook API cost?
Microsoft does not charge per Graph call for mail and calendar. What you pay for is the mailbox: a Microsoft 365 license for each work mailbox, or nothing for a personal Outlook.com account. The real costs are engineering ones: one integration for Microsoft and another for Google if your users are on both, as our Gmail API guide shows, and the time to keep tokens, subscriptions and delta links alive for every connected mailbox.
What breaks in production?
Webhooks that stop after a week. The symptom is a product that stops seeing new emails seven days after a mailbox connected. The cause is a subscription nobody renewed. Renew well before subscriptionExpirationDateTime, listen for lifecycle notifications, and alert when a mailbox has gone quiet for longer than usual.
A slow webhook endpoint. Graph considers a notification delivered when it gets a 2xx within 3 seconds. An endpoint where more than 10% of responses take longer is marked slow and its notifications are delayed by 10 minutes, and past 15% beyond 10 seconds notifications are dropped and cannot be recovered. Queue the notification, answer 202 at once, and process it afterwards.
Throttling on a busy mailbox. Graph limits Outlook calls per app and mailbox to 10,000 requests in 10 minutes and 4 concurrent requests, and answers 429 with a Retry-After header. Read the header, back off, and batch reads with $select and delta rather than polling.
An app that can send as the CEO. An application permission like Mail.Send covers every mailbox in the tenant until someone scopes it. Customers' security teams will ask, so scope it with RBAC for Applications before they do.
Too many subscriptions on one mailbox. Graph allows 1,000 active subscriptions per mailbox across all applications and refuses the next one with 403. Create one subscription per mailbox and resource, not one per feature.
A script still on EWS. Integrations built years ago on Exchange Web Services stop working as the shutdown reaches each tenant. Search the codebase for EWS endpoints now and move them to Graph.
Should you use the Outlook API directly or a provider?
| Your situation | What fits |
|---|---|
| Scripts on your own organization's mailboxes | Microsoft Graph directly, with an app registered in your tenant |
| Your users' Outlook and Gmail inside a CRM, helpdesk or AI assistant | Graph and the Gmail API, or a mailbox API that unifies them: Nylas, Unipile, EmailEngine |
| Outreach from many mailboxes, with caps, sequences and replies | An outreach API built for it |
The email API guide compares the three kinds of email API, and the EmailEngine review, Nylas pricing and Unipile review cover the mailbox APIs in depth.
The Swarmhit APIs sit in the third row. On the Swarmhit Smart API, a hosted connect link lets a person connect a Microsoft 365 mailbox by signing in on Microsoft's own page, and the engine then handles daily caps per mailbox, threading, reply detection and bounce suppression, with email steps in the same sequence as LinkedIn and WhatsApp steps; Microsoft 365 mailboxes bought through Swarmhit arrive connected and warming. On the Swarmhit Raw API, in early access, you connect Microsoft mailboxes with your own OAuth app's tokens or a service app's delegated access, and call one endpoint per action. Either way, each mailbox keeps Microsoft's own sending limits, and the cold email infrastructure guide covers domains, DNS and warmup before you send.
FAQ
Does Outlook have an API?
Yes: Microsoft Graph, at graph.microsoft.com. It reads, searches, sends and replies to email, syncs folders with delta queries, sends webhooks when messages arrive, and manages calendar events and contacts, for Microsoft 365 work accounts and personal Outlook.com accounts. The older Outlook REST API was decommissioned in March 2024, and Exchange Web Services is being switched off in Exchange Online.
Is the Outlook API free?
Microsoft does not charge per Graph call for mail and calendar. Each work mailbox needs its Microsoft 365 license, and personal Outlook.com accounts cost nothing. Usage is limited rather than billed: Graph throttles Outlook calls at 10,000 requests per 10 minutes and 4 concurrent requests for each app and mailbox, and every mailbox keeps Exchange Online's sending limits.
What is the difference between the Outlook REST API and Microsoft Graph?
The Outlook REST API was the older endpoint at outlook.office.com/api. Microsoft deprecated it and decommissioned it in March 2024. Microsoft Graph serves the same mail, calendar and contact resources at graph.microsoft.com, with the same permissions, camelCase property names instead of PascalCase, and one token for Outlook and other Microsoft 365 services. Graph v1.0 matches the old Outlook v2.0.
Can I use the Outlook API with a personal Outlook.com account?
Yes, with delegated permissions. Register the app for personal Microsoft accounts, or for work and personal accounts, and the user signs in and consents. Application permissions, where the app acts without a signed-in user, are not available for personal accounts, and an app open to personal accounts can request at most 30 permissions.
Do I need an API key for the Outlook API?
No. Microsoft Graph does not use API keys for mailbox data. Every call carries an OAuth access token from Microsoft Entra ID, obtained after a user signs in and consents, or with an administrator's consent for application permissions. Libraries such as MSAL for Python handle the sign-in and refresh the token.
What happens to Exchange Web Services in 2026?
Microsoft is switching EWS off in Exchange Online. Tenants still on the default setting lose it as the rollout reaches them from 1 October 2026, and the final shutdown is planned for 1 April 2027. Apps that still call EWS need to move to Microsoft Graph, which covers mail, calendar and contacts. Microsoft's retirement notice covers Exchange Online, the cloud service, and points every EWS app to Graph.




