Use the Microsoft Graph API to integrate with Outlook mail

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 permissions, your app can access the mail data of the signed-in user or any user in a tenant. The mail data can be in the cloud on Exchange Online as part of Office 365, or on Exchange on-premises in a hybrid deployment.

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.

Note: In general, do not assume that message and mailfolder IDs are unique and immutable within a mailbox. They might change after certain actions such as copy, move, or send.

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 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
Add, get, or delete attachments of a message attachment,
fileAttachment,
itemAttachment,
referenceAttachment,
message
Methods of attachment
Get or update a user's automatic reply, locale or time zone mailboxSettings,
automaticRepliesSetting,
localeInfo
Get user's mailbox settings,
Update user's mailbox settings
Mail and folder management
Organize messages in a mail folder hierarchy mailFolder Methods of mailFolder
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 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:

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