Use the Outlook mail REST API

Microsoft Graph lets your app get authorized access to a user's Outlook mail data in a personal or organization account. With the appropriate delegated or application mail permissions, your app can access the mail data of the signed-in user or any user in a tenant. For more information on access tokens, app registration, and delegated and application permissions, see Authentication and authorization basics.

The Microsoft Graph API supports accessing data in users' primary mailboxes and in shared mailboxes. The data can be calendar, mail, or personal contacts stored in a mailbox in the cloud on Exchange Online as part of Microsoft 365, or on Exchange on-premises in a hybrid deployment.

The API does not support accessing in-place archive mailboxes, not on Exchange Online nor on Exchange Server.

Using the mail REST API

Mail API requests are performed on behalf of a user which can be identified by the user's id property (a unique GUID), email address, or the me shortcut alias for the signed-in user.

Email messages are represented by the message resource and organized in a mailFolder. Messages and mail folders are identified by their id property, obtainable from GET operations.


In general, do not assume that message and mailfolder IDs are unique and always remain the same within a mailbox. They might change after certain actions such as copy or move. You can choose to use immutable IDs to retain the same ID as long as the message remains in the same mailbox, with the exception of sending a draft message, and a few other scenarios. See lifetime of immutable IDs for details.

Message bodies can be in HTML or text format.

You can use well-known folder names such as Inbox, Drafts, SentItems, or DeletedItems to identify certain mail folders that exist by default for all users. For a list of supported well-known folder names, see mailFolder resource type.

For example, you can get messages in the Outlook Sent Items folder of the signed-in user, without first getting the folder ID:

GET /me/mailFolders('SentItems')/messages?$select=sender,subject

Common use cases

The message resource exposes properties such as categories, conversationId, flag, and importance that correspond to features available in the UI, allowing apps to automate or integrate with the built-in Outlook user experience.

The Microsoft Graph API also provides methods and actions that support common use cases of messages.

Use cases REST resources See also
User-centric actions
Draft, read, reply, forward, send, update, or delete messages message Methods of message
Delegate another user to send messages on behalf of the mailbox owner message Setting the from and sender properties in a message
Let user view more important messages first inferenceClassificationOverride Focused Inbox
Query for messages and get them in a search folder mailSearchFolder Methods of mailSearchFolder
Get the MIME content of a message or message attachment message Get MIME content
Send messages with MIME content message Send MIME content
Add, get, or delete attachments of a message attachment,
Methods of attachment
Get language and time zone choices for a user localeInfo,
Get or update a user's automatic reply, locale, time zone, or working hours mailboxSettings,
Get user's mailbox settings,
Update user's mailbox settings
Get MailTips of other recipients' special status, such as out-of-office user,
Get MailTips
Mail and folder management
Organize messages in a mail folder hierarchy mailFolder Methods of mailFolder
Categorize messages outlookCategory Methods of outlookCategory
Use Inbox rules to automate actions such as forwarding specific incoming messages messageRule Methods of messageRule
Get Internet message headers of a message message Get the internetMessageHeaders property of a message.
Search and filter messages message Query parameters
Get notified of changes to messages in a folder subscription Working with webhooks in Microsoft Graph
Synchronize messages or mail folder hierarchy message Get incremental changes to messages in a folder
App development
Add custom app data as Internet message headers of a message message Add custom data to the internetMessageHeaders property of the message.
Add custom app data to a message by using extensions openTypeExtension,
Add custom data to resources using extensions
Access custom data for under-exposed Outlook MAPI properties singleValueLegacyExtendedProperty,
Outlook extended properties overview

What's new

Find out about the latest new features and updates for this API set.

Next steps

The mail API can open up new ways for you to engage with users:

Need more ideas? See how some of our partners are using Microsoft Graph.