Use the Outlook mail REST API
Important
APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.
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.
Important
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 | Set 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, fileAttachment, itemAttachment, referenceAttachment, message |
Methods of attachment |
| Get language and time zone choices for a user | localeInfo, timeZoneInformation |
supportedLanguages, supportedTimeZones |
| Get or update a user's automatic reply, locale, time zone, or working hours | mailboxSettings, automaticRepliesSetting, localeInfo, workingHours |
Get user's mailbox settings, Update user's mailbox settings |
| Get MailTips of other recipients' special status, such as out-of-office | user, mailTips |
Get MailTips |
| Alert user if mentioned in other messages (preview) | mention (preview) | Get details of @-mentions in a message |
| Unsubscribe user from an email distribution list (preview) | message (preview) | Unsubscribe |
| 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 collection of the message. |
| Add custom app data to a message by using extensions | openTypeExtension, schemaExtension |
Add custom data to resources using extensions |
| Access custom data for under-exposed Outlook MAPI properties | singleValueLegacyExtendedProperty, multiValueLegacyExtendedProperty |
Outlook extended properties overview |
Next steps
The mail API can open up new ways for you to engage with users:
- Outlook mail API overview
- Drill down on the methods, properties, and relationships of the message and mailFolder resources.
- Try the API in the Graph Explorer.
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for