Microsoft Graph: Outlook Mail
Read, search, send, reply to, move and flag email in Outlook and Exchange Online mailboxes, manage mail folders, attachments, rules and mailbox settings. This…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
Read, search, send, reply to, move and flag email in Outlook and Exchange Online mailboxes, manage mail folders, attachments, rules and mailbox settings.
This listing is one area of Microsoft Graph, the single REST API for Microsoft 365, Outlook, OneDrive, Teams and Microsoft Entra ID. It holds 113 of the area's requests, the most direct ones first, generated from Microsoft's own OpenAPI description of Graph v1.0. The other areas (mail, calendar, files, Teams, users and more) are listed separately on the Microsoft page.
Get an access token
- Sign in to the Microsoft Entra admin center and open App registrations > New registration. For a quick test, the Graph Explorer signs you in and shows a token without registering anything.
- Under API permissions, add the Microsoft Graph permissions this area needs, for example:
Mail.Read,Mail.ReadWrite,Mail.Send,MailboxSettings.ReadWrite. Delegated permissions act as the signed-in user; application permissions act as the app itself and need an administrator's consent. - Under Certificates & secrets, create a client secret (keep it out of shared collections).
- Get a token from
https://login.microsoftonline.com/ /oauth2/v2.0/token: the authorization-code flow for a user, orgrant_type=client_credentialswithscope=https://graph.microsoft.com/.defaultfor an app. Send it asAuthorization: Bearer.
Using these requests
- Base URL:
https://graph.microsoft.com/v1.0./me/...paths act on the signed-in user; with an application token use/users/{id or userPrincipalName}/...instead. - Shape responses with OData query parameters:
$select(fields),$filter,$orderby,$top,$expandand$search(some need theConsistencyLevel: eventualheader). Long lists are paged: follow@odata.nextLink. - Combine up to 20 requests in one call with
POST /$batch.
Common errors
| Status | Code | What to do |
|---|---|---|
| 401 | InvalidAuthenticationToken | The token is missing, expired or for another resource: get a new one for https://graph.microsoft.com. |
| 403 | Authorization_RequestDenied / ErrorAccessDenied | Add the permission listed in the request's docs and grant consent. |
| 404 | ResourceNotFound / itemNotFound | Check the id; ids from another user or tenant are not found. |
| 429 | TooManyRequests | Throttled: wait the Retry-After seconds, then retry. |
Docs: Outlook Mail overview · Permissions reference · Throttling
Endpoints 113
Messages
- GETList messages
/me/messagesGet an open extension (openTypeExtension object) identified by name or fully qualified name. The table in the Permissions section lists the resources that… - POSTCreate message
/me/messagesCreate an open extension (openTypeExtension object) and add custom properties in a new or existing instance of a resource. You can create an open extension in… - GETTrack changes to messages (delta)
/me/messages/delta()Get a set of messages added, deleted, or updated in a specified folder. A delta function call for messages in a folder is similar to a GET request, except… - GETGet message
/me/messages/:message-idGet the properties and relationships of the eventMessage object. Apply the $expand parameter on the event navigation property to get the associated event in… - DELETEDelete message
/me/messages/:message-idDelete eventMessage. - PATCHUpdate message
/me/messages/:message-idUpdate the properties of an eventMessage object. - POSTCopy message
/me/messages/:message-id/copyCopy a message to a folder within the user's mailbox. - POSTMove message
/me/messages/:message-id/moveMove a message to another folder within the specified user's mailbox. This creates a new copy of the message in the destination folder and removes the… - POSTSend message
/me/messages/:message-id/sendSend an existing draft message. The draft message can be a new message draft, reply draft, reply-all draft, or a forward draft. This method saves the message… - POSTReply message
/me/messages/:message-id/replyReply to the sender of a message using either JSON or MIME format. When using JSON format: * Specify either a comment or the body property of the message… - GETDownload content
/me/messages/:message-id/$valueGet an open extension (openTypeExtension object) identified by name or fully qualified name. The table in the Permissions section lists the resources that… - PUTUpload content
/me/messages/:message-id/$valueUpdate the properties of an eventMessage object. - DELETEUpload content
/me/messages/:message-id/$valueDelete eventMessage. - POSTForward message
/me/messages/:message-id/forwardForward a message using either JSON or MIME format. When using JSON format, you can: Specify either a comment or the body property of the message parameter.… - POSTReply all (message)
/me/messages/:message-id/replyAllReply to all recipients of a message using either JSON or MIME format. When using JSON format: Specify either a comment or the body property of the message… - POSTCreate reply (message)
/me/messages/:message-id/createReplyCreate a draft to reply to the sender of a message in either JSON or MIME format. When using JSON format: Specify either a comment or the body property of the… - POSTCreate forward (message)
/me/messages/:message-id/createForward - POSTCreate reply all (message)
/me/messages/:message-id/createReplyAllCreate a draft to reply to the sender and all recipients of a message in either JSON or MIME format. When using JSON format: Specify either a comment or the… - POSTPermanent delete (message)
/me/messages/:message-id/permanentDelete
Messages: extensions
- GETList extensions
/me/messages/:message-id/extensionsGet an open extension (openTypeExtension object) identified by name or fully qualified name. The table in the Permissions section lists the resources that… - POSTCreate extension
/me/messages/:message-id/extensionsCreate an open extension (openTypeExtension object) and add custom properties in a new or existing instance of a resource. You can create an open extension in… - GETGet extension
/me/messages/:message-id/extensions/:extension-idGet an open extension (openTypeExtension object) identified by name or fully qualified name. The table in the Permissions section lists the resources that… - DELETEDelete extension
/me/messages/:message-id/extensions/:extension-idDelete an open extension (openTypeExtension object) from the specified instance of a resource. For the list of resources that support open extensions, see the… - PATCHUpdate extension
/me/messages/:message-id/extensions/:extension-id
Messages: attachments
- GETList attachments
/me/messages/:message-id/attachmentsRetrieve a list of attachment objects. - POSTCreate attachment
/me/messages/:message-id/attachmentsUse this API to create a new Attachment. An attachment can be one of the following types: All these types of attachment resources are derived from the… - GETGet attachment
/me/messages/:message-id/attachments/:attachment-idRead the properties, relationships, or raw contents of an attachment that is attached to a user event, message, or group post. An attachment can be one of the… - DELETEDelete attachment
/me/messages/:message-id/attachments/:attachment-id - POSTCreate upload session (attachment)
/me/messages/:message-id/attachments/createUploadSessionCreate an upload session that allows an app to iteratively upload ranges of a file, so as to attach the file to the specified Outlook item. The item can be a…
Actions and more
- POSTSend mail
/me/sendMailSend the message specified in the request body using either JSON or MIME format. When using JSON format, you can include a file attachment in the same… - POSTGet mail tips
/me/getMailTipsGet the MailTips of one or more recipients as available to the signed-in user. Note that by making a POST call to the getMailTips action, you can request… - POSTTranslate exchange ids
/me/translateExchangeIdsTranslate identifiers of Outlook-related resources between formats.
Mail folders
- GETList mail folders
/me/mailFoldersGet the mail folder collection directly under the root folder of the signed-in user. The returned collection includes any mail search folders directly under… - POSTCreate mail folder
/me/mailFoldersUse this API to create a new mail folder in the root folder of the user's mailbox. If you intend a new folder to be hidden, you must set the isHidden property… - GETTrack changes to mail folders (delta)
/me/mailFolders/delta()Get a set of mail folders that have been added, deleted, or removed from the user's mailbox. A delta function call for mail folders in a mailbox is similar to… - GETGet mail folder
/me/mailFolders/:mailFolder-idRetrieve the properties and relationships of a message folder object. The following list shows the two existing scenarios where an app can get another user's… - DELETEDelete mail folder
/me/mailFolders/:mailFolder-idDelete the specified mailFolder. The folder can be a mailSearchFolder. You can specify a mail folder by its folder ID, or by its well-known folder name, if… - PATCHUpdate mail folder
/me/mailFolders/:mailFolder-idUpdate the properties of mailfolder object. - POSTCopy mail folder
/me/mailFolders/:mailFolder-id/copyCopy a mailfolder and its contents to another mailfolder. - POSTMove mail folder
/me/mailFolders/:mailFolder-id/moveMove a mailfolder and its contents to another mailfolder. - POSTPermanent delete (mail folder)
/me/mailFolders/:mailFolder-id/permanentDelete
Mail folders: messages
- GETList messages
/me/mailFolders/:mailFolder-id/messagesGet all the messages in the specified user's mailbox, or those messages in a specified folder in the mailbox. - POSTCreate message
/me/mailFolders/:mailFolder-id/messagesUse this API to create a new Message in a mailfolder. - GETTrack changes to messages (delta)
/me/mailFolders/:mailFolder-id/messages/delta()Get a set of messages added, deleted, or updated in a specified folder. A delta function call for messages in a folder is similar to a GET request, except… - GETGet message
/me/mailFolders/:mailFolder-id/messages/:message-idThe collection of messages in the mailFolder. - DELETEDelete message
/me/mailFolders/:mailFolder-id/messages/:message-id - PATCHUpdate message
/me/mailFolders/:mailFolder-id/messages/:message-id - POSTCopy message
/me/mailFolders/:mailFolder-id/messages/:message-id/copyCopy a message to a folder within the user's mailbox. - POSTMove message
/me/mailFolders/:mailFolder-id/messages/:message-id/moveMove a message to another folder within the specified user's mailbox. This creates a new copy of the message in the destination folder and removes the… - POSTSend message
/me/mailFolders/:mailFolder-id/messages/:message-id/sendSend an existing draft message. The draft message can be a new message draft, reply draft, reply-all draft, or a forward draft. This method saves the message… - POSTReply message
/me/mailFolders/:mailFolder-id/messages/:message-id/replyReply to the sender of a message using either JSON or MIME format. When using JSON format: * Specify either a comment or the body property of the message… - GETDownload mail folder content
/me/mailFolders/:mailFolder-id/messages/:message-id/$valueGet all the messages in the specified user's mailbox, or those messages in a specified folder in the mailbox. - PUTUpload mail folder content
/me/mailFolders/:mailFolder-id/messages/:message-id/$valueThe unique identifier for an entity. Read-only. - DELETEUpload mail folder content
/me/mailFolders/:mailFolder-id/messages/:message-id/$valueThe unique identifier for an entity. Read-only. - POSTForward message
/me/mailFolders/:mailFolder-id/messages/:message-id/forwardForward a message using either JSON or MIME format. When using JSON format, you can: Specify either a comment or the body property of the message parameter.… - POSTReply all (message)
/me/mailFolders/:mailFolder-id/messages/:message-id/replyAllReply to all recipients of a message using either JSON or MIME format. When using JSON format: Specify either a comment or the body property of the message… - GETList extensions
/me/mailFolders/:mailFolder-id/messages/:message-id/extensionsThe collection of open extensions defined for the message. Nullable. - POSTCreate extension
/me/mailFolders/:mailFolder-id/messages/:message-id/extensions - GETList attachments
/me/mailFolders/:mailFolder-id/messages/:message-id/attachmentsThe fileAttachment and itemAttachment attachments for the message. - POSTCreate attachment
/me/mailFolders/:mailFolder-id/messages/:message-id/attachments - POSTCreate reply (message)
/me/mailFolders/:mailFolder-id/messages/:message-id/createReplyCreate a draft to reply to the sender of a message in either JSON or MIME format. When using JSON format: Specify either a comment or the body property of the… - POSTCreate forward (message)
/me/mailFolders/:mailFolder-id/messages/:message-id/createForward - POSTCreate reply all (message)
/me/mailFolders/:mailFolder-id/messages/:message-id/createReplyAllCreate a draft to reply to the sender and all recipients of a message in either JSON or MIME format. When using JSON format: Specify either a comment or the… - POSTPermanent delete (message)
/me/mailFolders/:mailFolder-id/messages/:message-id/permanentDelete - GETGet extension
/me/mailFolders/:mailFolder-id/messages/:message-id/extensions/:extension-idThe collection of open extensions defined for the message. Nullable. - DELETEDelete extension
/me/mailFolders/:mailFolder-id/messages/:message-id/extensions/:extension-id - PATCHUpdate extension
/me/mailFolders/:mailFolder-id/messages/:message-id/extensions/:extension-id - GETGet attachment
/me/mailFolders/:mailFolder-id/messages/:message-id/attachments/:attachment-idThe fileAttachment and itemAttachment attachments for the message. - DELETEDelete attachment
/me/mailFolders/:mailFolder-id/messages/:message-id/attachments/:attachment-id - POSTCreate upload session (attachment)
/me/mailFolders/:mailFolder-id/messages/:message-id/attachments/createUploadSessionCreate an upload session that allows an app to iteratively upload ranges of a file, so as to attach the file to the specified Outlook item. The item can be a…
Mail folders: child folders
- GETList child folders
/me/mailFolders/:mailFolder-id/childFoldersGet the folder collection under the specified folder. You can use the .../me/mailFolders shortcut to get the top-level folder collection and navigate to… - POSTCreate child folder
/me/mailFolders/:mailFolder-id/childFoldersUse this API to create a new child mailFolder. If you intend a new folder to be hidden, you must set the isHidden property to true on creation. - GETTrack changes to child folders (delta)
/me/mailFolders/:mailFolder-id/childFolders/delta()Get a set of mail folders that have been added, deleted, or removed from the user's mailbox. A delta function call for mail folders in a mailbox is similar to… - GETGet child folder
/me/mailFolders/:mailFolder-id/childFolders/:mailFolder-id1The collection of child folders in the mailFolder. - DELETEDelete child folder
/me/mailFolders/:mailFolder-id/childFolders/:mailFolder-id1 - PATCHUpdate child folder
/me/mailFolders/:mailFolder-id/childFolders/:mailFolder-id1 - POSTCopy child folder
/me/mailFolders/:mailFolder-id/childFolders/:mailFolder-id1/copyCopy a mailfolder and its contents to another mailfolder. - POSTMove child folder
/me/mailFolders/:mailFolder-id/childFolders/:mailFolder-id1/moveMove a mailfolder and its contents to another mailfolder. - GETList messages
/me/mailFolders/:mailFolder-id/childFolders/:mailFolder-id1/messagesThe collection of messages in the mailFolder. - POSTCreate message
/me/mailFolders/:mailFolder-id/childFolders/:mailFolder-id1/messages - GETList message rules
/me/mailFolders/:mailFolder-id/childFolders/:mailFolder-id1/messageRulesThe collection of rules that apply to the user's Inbox folder. - POSTCreate message rule
/me/mailFolders/:mailFolder-id/childFolders/:mailFolder-id1/messageRules - POSTPermanent delete (child folder)
/me/mailFolders/:mailFolder-id/childFolders/:mailFolder-id1/permanentDelete - GETTrack changes to messages (delta)
/me/mailFolders/:mailFolder-id/childFolders/:mailFolder-id1/messages/delta()Get a set of messages added, deleted, or updated in a specified folder. A delta function call for messages in a folder is similar to a GET request, except… - GETGet message
/me/mailFolders/:mailFolder-id/childFolders/:mailFolder-id1/messages/:message-idThe collection of messages in the mailFolder. - DELETEDelete message
/me/mailFolders/:mailFolder-id/childFolders/:mailFolder-id1/messages/:message-id - PATCHUpdate message
/me/mailFolders/:mailFolder-id/childFolders/:mailFolder-id1/messages/:message-id - GETGet message rule
/me/mailFolders/:mailFolder-id/childFolders/:mailFolder-id1/messageRules/:messageRule-idThe collection of rules that apply to the user's Inbox folder. - DELETEDelete message rule
/me/mailFolders/:mailFolder-id/childFolders/:mailFolder-id1/messageRules/:messageRule-id - PATCHUpdate message rule
/me/mailFolders/:mailFolder-id/childFolders/:mailFolder-id1/messageRules/:messageRule-id
Mail folders: message rules
- GETList message rules
/me/mailFolders/:mailFolder-id/messageRulesGet all the messageRule objects defined for the user's inbox. - POSTCreate message rule
/me/mailFolders/:mailFolder-id/messageRulesCreate a messageRule object by specifying a set of conditions and actions. Outlook carries out those actions if an incoming message in the user's Inbox meets… - GETGet message rule
/me/mailFolders/:mailFolder-id/messageRules/:messageRule-idGet the properties and relationships of a messageRule object. - DELETEDelete message rule
/me/mailFolders/:mailFolder-id/messageRules/:messageRule-idDelete the specified messageRule object. - PATCHUpdate message rule
/me/mailFolders/:mailFolder-id/messageRules/:messageRule-idChange writable properties on a messageRule object and save the changes.
Outlook
- GETGet outlook
/me/outlook - GETSupported languages (outlook)
/me/outlook/supportedLanguages()Get the list of locales and languages that are supported for the user, as configured on the user's mailbox server. When setting up an Outlook client, the user… - GETSupported time zones (outlook)
/me/outlook/supportedTimeZones()Get the list of time zones that are supported for the user, as configured on the user's mailbox server. You can explicitly specify to have time zones returned… - GETGet outlook
/me/outlook/supportedTimeZones(TimeZoneStandard=':TimeZoneStandard')Get the list of time zones that are supported for the user, as configured on the user's mailbox server. You can explicitly specify to have time zones returned…
Mailbox settings
- GETGet mailbox settings
/me/mailboxSettingsGet the user's mailboxSettings. You can view all mailbox settings, or get specific settings. Users can set the following settings for their mailboxes through… - PATCHUpdate mailbox settings
/me/mailboxSettingsEnable, configure, or disable one or more of the following settings as part of a user's mailboxSettings: When updating the preferred date or time format for a…
Inference classification
- GETGet inference classification
/me/inferenceClassificationRelevance classification of the user's messages based on explicit designations that override inferred relevance or importance. - PATCHUpdate inference classification
/me/inferenceClassification
Outlook: master categories
- GETList master categories
/me/outlook/masterCategoriesGet all the categories that have been defined for a user. - POSTCreate master category
/me/outlook/masterCategoriesCreate an outlookCategory object in the user's master list of categories. - GETGet master category
/me/outlook/masterCategories/:outlookCategory-idGet the properties and relationships of the specified outlookCategory object. - DELETEDelete master category
/me/outlook/masterCategories/:outlookCategory-idDelete the specified outlookCategory object. - PATCHUpdate master category
/me/outlook/masterCategories/:outlookCategory-idUpdate the writable property, color, of the specified outlookCategory object. You can't modify the displayName property once you have created the category.
Inference classification: overrides
- GETList overrides
/me/inferenceClassification/overridesGet the overrides that a user has set up to always classify messages from certain senders in specific ways. Each override corresponds to an SMTP address of a… - POSTCreate override
/me/inferenceClassification/overridesCreate an override for a sender identified by an SMTP address. Future messages from that SMTP address will be consistently classified as specified in the… - GETGet override
/me/inferenceClassification/overrides/:inferenceClassificationOverride-idA set of overrides for a user to always classify messages from specific senders in certain ways: focused, or other. Read-only. Nullable. - DELETEDelete override
/me/inferenceClassification/overrides/:inferenceClassificationOverride-idDelete an override specified by its ID. - PATCHUpdate override
/me/inferenceClassification/overrides/:inferenceClassificationOverride-idChange the classifyAs field of an override as specified. You cannot use PATCH to change any other fields in an inferenceClassificationOverride instance. If an…
API details
- Base URL
https://graph.microsoft.com/v1.0- Authentication
- OAuth 2.0 (authorization code, client credentials flows)
- Operations
- 113 operations on 70 pathsPOST 44GET 39DELETE 15PATCH 13PUT 2
- Main resources
- Mail folders: messages 29Mail folders: child folders 20Messages 19Mail folders 9Inference classification: overrides 5Mail folders: message rules 5Messages: attachments 5Messages: extensions 5Outlook: master categories 5Outlook 4
- Description format
- OpenAPI 3.0.4, API version
v1.0 - Links
- Documentation · OpenAPI document
How to test the Microsoft Graph: Outlook Mail in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Microsoft Graph: Outlook Mail collection, without the publisher's secrets.
- Add your credentialsThis API uses OAuth 2.0 (authorization code, client credentials flows). Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “List messages” (GET /me/messages), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Microsoft Graph: Outlook Mail?
Read, search, send, reply to, move and flag email in Outlook and Exchange Online mailboxes, manage mail folders, attachments, rules and mailbox settings. This… It is listed under Communication and has 113 endpoints.
Who publishes the Microsoft Graph: Outlook Mail?
It is listed from Microsoft's public API description (an OpenAPI document), not published by Microsoft on Swastik Codes. Anyone who controls microsoft.com can claim the profile by adding a DNS TXT record.
What is the base URL of the Microsoft Graph: Outlook Mail?
Requests go to https://graph.microsoft.com/v1.0. Endpoint paths are added to this base URL.
How do I authenticate with the Microsoft Graph: Outlook Mail?
With OAuth 2.0 (authorization code, client credentials flows).
How many endpoints does the Microsoft Graph: Outlook Mail have?
113 operations on 70 paths (44 POST, 39 GET, 15 DELETE, 13 PATCH, 2 PUT). The largest groups are Mail folders: messages, Mail folders: child folders, Messages, Mail folders.
Is forking the Microsoft Graph: Outlook Mail free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.