A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Microsoft Outlook API is how an app or AI agent works with a user's Outlook mailbox: listing and reading messages, sending and replying to mail, creating and updating calendar events, and managing contacts. Access is granted through an OAuth 2.0 token and a set of Microsoft Graph permissions that decide which mailbox a call can reach and whether it can read or write, with sending mail gated by its own permission. Outlook can also push a change notification when a message, event, or contact changes, so an agent learns of activity without polling.
How an app or AI agent connects to Microsoft Outlook determines what it can reach. Outlook is part of Microsoft Graph, so a call goes through one route for making requests and one for receiving events, each governed by an access token and the permissions that token carries.
Outlook mail, calendar, and contacts are reached through Microsoft Graph, a single REST API for Microsoft 365 data. A call sends and receives JSON over HTTPS, authenticates with an OAuth 2.0 bearer token from the Microsoft identity platform, and addresses Outlook data under the signed-in user at /me or a named user at /users/{id}. The production endpoint is https://graph.microsoft.com/v1.0.
Microsoft Graph delivers a change notification to a registered HTTPS notification URL when an Outlook message, event, or contact is created, updated, or deleted. A subscription names the resource, the changeType, and the URL, and Graph validates the URL before it starts sending. A subscription expires and must be renewed before it lapses.
Microsoft's first-party MCP server at https://mcp.svc.cloud.microsoft/enterprise lets an AI agent query Microsoft Graph in natural language, with tools microsoft_graph_suggest_queries, microsoft_graph_get, and microsoft_graph_list_properties. It is in public preview, and its current scope is read-only Microsoft Entra identity and directory data, not the Outlook mail and calendar surface, which is reached through the Graph REST API. Every call honors the user's roles and granted scopes.
A delegated token represents a signed-in user, so a call can do only what both the app's permissions and that user allow. Delegated access reaches the signed-in user's own mailbox; it cannot subscribe to or act on another user's mailbox unless that mailbox is explicitly shared or delegated.
An app-only token represents the application itself with no user present, using permissions like Mail.Read or Mail.Send that an administrator consents to. App-only permissions ending in .All can reach any mailbox in the tenant, so application access is what an agent uses to watch or act on mailboxes other than the signed-in user's. Exchange application access policies can scope which mailboxes an app reaches.
A personal Microsoft account, such as an outlook.com mailbox, signs in through the same OAuth 2.0 flow and uses the same delegated mail, calendar, and contacts permissions as a work or school account. App-only access is not available for personal accounts.
The Outlook surface of Microsoft Graph is split into areas an agent can act on, like messages, mail folders, calendar events, and contacts. Each area has its own methods and its own permissions, and sending mail or changing the calendar reaches further than reading does.
List, read, create, update, and delete messages, and send, reply, reply-all, forward, move, and copy them.
List, read, create, update, and delete mail folders such as Inbox, Drafts, and Sent Items.
List, read, create, update, and delete calendar events, and accept, tentatively accept, or decline meeting invitations.
List, read, create, update, and delete the contacts in a user's mailbox.
Create and delete subscriptions that push change notifications for Outlook messages, events, and contacts.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
MessagesList, read, create, update, and delete messages, and send, reply, reply-all, forward, move, and copy them.12 | ||||||
| GET | /me/messages | List the messages in the signed-in user's mailbox, across folders. | read | Mail.ReadBasic | Current | |
Mail.ReadBasic is the least-privileged delegated and application permission and excludes the message body; Mail.Read returns the full message. The application permission is Mail.ReadBasic.All. Acts onmessage Permission (capability) Mail.ReadBasicVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /me/mailFolders/{id}/messages | List the messages in a specific mail folder, such as the Inbox. | read | Mail.ReadBasic | Current | |
A well-known folder name like inbox, drafts, or sentitems can be used in place of the folder id. Acts onmessage Permission (capability) Mail.ReadBasicVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /me/messages/{id} | Read the properties and relationships of a single message. | read | Mail.Read | Current | |
Mail.Read returns the full message including the body. The application permission is Mail.Read. Acts onmessage Permission (capability) Mail.ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /me/messages | Create a draft of a new message in the mailbox. | write | Mail.ReadWrite | Current | |
Creating a draft does not send it; sending needs Mail.Send. The application permission is Mail.ReadWrite. Acts onmessage Permission (capability) Mail.ReadWriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /me/sendMail | Compose and send a message in one call, saving it to Sent Items. | write | Mail.Send | Current | |
Mail.Send is the only permission, delegated and application. It returns 202 Accepted, which confirms the request was accepted, not that delivery completed. Acts onmessage Permission (capability) Mail.SendVersionAvailable since the API’s base version Webhook eventNone Rate limitUp to 150 MB of message content per 5 minutes per mailbox. SourceOfficial documentation ↗ | ||||||
| POST | /me/messages/{id}/send | Send a previously created draft message. | write | Mail.Send | Current | |
Sends the draft and saves it to Sent Items. The application permission is Mail.Send. Acts onmessage Permission (capability) Mail.SendVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /me/messages/{id}/reply | Reply to the sender of a message and save the reply to Sent Items. | write | Mail.Send | Current | |
Sends immediately. To draft a reply for later editing, use createReply instead, which needs Mail.ReadWrite. Acts onmessage Permission (capability) Mail.SendVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /me/messages/{id}/replyAll | Reply to all recipients of a message and save the reply to Sent Items. | write | Mail.Send | Current | |
Sends immediately to every recipient on the original message. Acts onmessage Permission (capability) Mail.SendVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /me/messages/{id}/forward | Forward a message to new recipients and save it to Sent Items. | write | Mail.Send | Current | |
Sends immediately. To draft a forward for later, use createForward, which needs Mail.ReadWrite. Acts onmessage Permission (capability) Mail.SendVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /me/messages/{id} | Update a message, such as its read state, categories, or flag. | write | Mail.ReadWrite | Current | |
The application permission is Mail.ReadWrite. Acts onmessage Permission (capability) Mail.ReadWriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /me/messages/{id}/move | Move a message to another folder, creating a copy in the destination. | write | Mail.ReadWrite | Current | |
Moving assigns the message a new id in the destination folder. Acts onmessage Permission (capability) Mail.ReadWriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /me/messages/{id} | Delete a message, moving it to the Deleted Items folder. | write | Mail.ReadWrite | Current | |
A standard delete is recoverable from Deleted Items; permanentDelete bypasses that. Acts onmessage Permission (capability) Mail.ReadWriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Mail foldersList, read, create, update, and delete mail folders such as Inbox, Drafts, and Sent Items.5 | ||||||
| GET | /me/mailFolders | List the mail folders in the user's mailbox. | read | Mail.ReadBasic | Current | |
Hidden folders are excluded unless the includeHiddenFolders=true query parameter is used. The application permission is Mail.ReadBasic.All. Acts onmailFolder Permission (capability) Mail.ReadBasicVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /me/mailFolders/{id} | Read the properties of a single mail folder. | read | Mail.ReadBasic | Current | |
A well-known name like inbox or drafts works in place of the folder id. Acts onmailFolder Permission (capability) Mail.ReadBasicVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /me/mailFolders | Create a new mail folder in the root of the mailbox. | write | Mail.ReadWrite | Current | |
The isHidden property can be set only at creation and cannot be changed by a later update. Acts onmailFolder Permission (capability) Mail.ReadWriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /me/mailFolders/{id} | Update a mail folder, such as its display name. | write | Mail.ReadWrite | Current | |
The application permission is Mail.ReadWrite. Acts onmailFolder Permission (capability) Mail.ReadWriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /me/mailFolders/{id} | Delete a mail folder and its contents. | write | Mail.ReadWrite | Current | |
Deletes the folder along with the messages it holds. Acts onmailFolder Permission (capability) Mail.ReadWriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Calendar & eventsList, read, create, update, and delete calendar events, and accept, tentatively accept, or decline meeting invitations.6 | ||||||
| GET | /me/events | List the events in the user's calendar. | read | Calendars.Read | Current | |
Returns single instances and recurring-series masters. The application permission is Calendars.Read. Acts onevent Permission (capability) Calendars.ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /me/events/{id} | Read the properties and relationships of a single event. | read | Calendars.Read | Current | |
The application permission is Calendars.Read. Acts onevent Permission (capability) Calendars.ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /me/events | Create an event in the user's default calendar. | write | Calendars.ReadWrite | Current | |
Adding attendees sends them a meeting invitation. The application permission is Calendars.ReadWrite. Acts onevent Permission (capability) Calendars.ReadWriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /me/events/{id} | Update an event, such as its time, location, or attendees. | write | Calendars.ReadWrite | Current | |
Updating a meeting can send an update to attendees. Acts onevent Permission (capability) Calendars.ReadWriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /me/events/{id} | Delete an event from the calendar. | write | Calendars.ReadWrite | Current | |
Deleting a meeting the user organizes cancels it for attendees. Acts onevent Permission (capability) Calendars.ReadWriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /me/events/{id}/accept | Accept a meeting invitation in the user's calendar. | write | Calendars.ReadWrite | Current | |
Companion actions decline and tentativelyAccept respond the other ways. Applies to user calendars only. Acts onevent Permission (capability) Calendars.ReadWriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ContactsList, read, create, update, and delete the contacts in a user's mailbox.5 | ||||||
| GET | /me/contacts | List the contacts in the user's mailbox. | read | Contacts.Read | Current | |
The application permission is Contacts.Read. Acts oncontact Permission (capability) Contacts.ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /me/contacts/{id} | Read the properties and relationships of a single contact. | read | Contacts.Read | Current | |
The application permission is Contacts.Read. Acts oncontact Permission (capability) Contacts.ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /me/contacts | Create a contact in the root Contacts folder. | write | Contacts.ReadWrite | Current | |
The application permission is Contacts.ReadWrite. Acts oncontact Permission (capability) Contacts.ReadWriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /me/contacts/{id} | Update a contact's properties. | write | Contacts.ReadWrite | Current | |
Include displayName in an update to preserve a value that would otherwise be regenerated. Acts oncontact Permission (capability) Contacts.ReadWriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /me/contacts/{id} | Delete a contact from the mailbox. | write | Contacts.ReadWrite | Current | |
The application permission is Contacts.ReadWrite. Acts oncontact Permission (capability) Contacts.ReadWriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Change notificationsCreate and delete subscriptions that push change notifications for Outlook messages, events, and contacts.2 | ||||||
| POST | /subscriptions | Create a subscription to receive change notifications for an Outlook resource. | write | Mail.Read | Current | |
The permission matches the resource being watched: Mail.Read for messages, Calendars.Read for events, Contacts.Read for contacts. A subscription has an expiry and must be renewed. Acts onsubscription Permission (capability) Mail.ReadVersionAvailable since the API’s base version Webhook event outlook-changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /subscriptions/{id} | Delete a subscription to stop receiving change notifications. | write | Mail.Read | Current | |
Stops delivery to the notification URL registered on the subscription. Acts onsubscription Permission (capability) Mail.ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Microsoft Graph can notify an app or AI agent when an Outlook message, event, or contact is created, updated, or deleted, instead of the app polling for changes. A subscription registers a notification URL, and Graph posts a change notification to it when the chosen change happens.
| Event | What it signals | Triggered by |
|---|---|---|
created / updated / deleted | Fires when an Outlook message, event, or contact is created, updated, or deleted, for whichever changeType the subscription requested. Microsoft Graph posts a change notification to the subscription's notification URL, identifying the resource and the change. | /subscriptions |
Microsoft Graph limits how fast and how much an app or AI agent can call Outlook, through a per-mailbox request budget for each application and a separate cap on how many requests run at once against one mailbox.
The Outlook service applies its limits to each combination of application and mailbox, so a budget belongs to one app accessing one user's or group's mailbox, and going over for one mailbox does not affect the app's access to another. An application is allowed up to 10,000 requests every 10 minutes per mailbox, and no more than 4 requests can run at once against a single mailbox. These are fixed service limits and are not raised on request. Microsoft Graph signals throttling with HTTP 429 and a Retry-After header in seconds, on top of which Exchange Online applies its own delivery and sending limits to mail that is sent.
Collection responses are paged. A list of messages defaults to 10 items and can be raised up to 1,000 with $top. When more results remain, the response includes an @odata.nextLink URL, which should be followed exactly as returned to get the next page rather than rebuilding it by hand, since it encodes server-side paging state. Outlook resources also support delta query to track only what changed since a previous call.
A single message can have at most 500 recipients across the To, Cc, and Bcc fields, and an event at most 500 attendees. Sending mail is held to 150 MB of message content per 5 minutes per mailbox. A request that returns a large page of full message bodies can hit a gateway timeout, so $select is used to return only the needed properties.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | badRequest | The request is malformed or incorrect, such as an invalid body or query, or invalid base64 MIME content on a send. | Read the error code and message, correct the request, and resend. The request is not retryable as-is. |
| 401 | InvalidAuthenticationToken | Required authentication information is missing or the access token is invalid or expired. | Acquire a fresh token from the Microsoft identity platform and send it in the Authorization header. |
| 403 | accessDenied | Access is denied. The token lacks the required permission or the user lacks a needed license, or a conditional access policy blocked the call. | Grant the missing Graph permission and consent to it, then confirm the user has access to the mailbox. |
| 404 | itemNotFound | The requested resource does not exist, or the token cannot see it. | Confirm the path and id, and that the token has access to the mailbox and resource. |
| 429 | TooManyRequests | The app has been throttled for exceeding a per-mailbox or service limit. The response carries a Retry-After header. | Wait the number of seconds in the Retry-After header before retrying, and reduce the request rate. |
| 503 | serviceUnavailable | The service is temporarily unavailable for maintenance or is overloaded. | Retry after the delay in the Retry-After header, or use exponential backoff if none is present. |
Microsoft Graph has two named endpoints. The v1.0 endpoint is the production version covered here, and a separate beta endpoint carries early features that are not supported for production use.
The v1.0 endpoint at https://graph.microsoft.com/v1.0 is the generally available, production-ready version of Microsoft Graph, including the Outlook mail, calendar, and contacts APIs. Microsoft Graph uses two named endpoints, v1.0 and beta, rather than dated versions; new features generally debut in beta and are promoted into v1.0 when ready. A version or API is declared deprecated at least 24 months before it is retired.
The beta endpoint at https://graph.microsoft.com/beta carries APIs and features that are in development. Breaking changes and deprecations can happen on beta without notice, and Microsoft does not support its use in production. Outlook features that are still previewing appear here before any promotion to v1.0.
A deprecated version or method is supported for at least 24 months after the deprecation is announced.
Microsoft Graph changelog ↗Bollard AI sits between a team's AI agents and Microsoft Outlook. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.