[DEPRECATED] Outlook Mail REST API reference (beta)
Applies to: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com
Note
The beta version of the Outlook REST API is deprecated.
As announced on November 17, 2020, version 2.0 of the Outlook REST API has been deprecated. Consequently, the beta REST endpoint is also deprecated and will be fully decommissioned in November 2022. Migrate existing apps to use Microsoft Graph. See a comparison to start your migration.
Not interested in the beta version of the API? In the table of contents on the left, go to the Office 365 REST API reference section and select the version you want.
All Mail API operations
Message operations
Messages are stored in mailbox folders, so message endpoints often include the folder that contains the message. A folder is either specified by ID or by one of the following well-known folder names: Inbox, Drafts, SentItems, or DeletedItems.
- Get messages
- Synchronize messages
- Create and send messages
- Reply or reply all to messages
- Forward new or drafted messages
- Update messages
- Delete messages
- Move or copy messages
- Manage Focused Inbox
- Manage @-Mentions (preview)
- Manage rules (preview)
- Unsubscribe (preview)
- Get language choices (preview)
- Get time zone choices (preview)
- Get mailbox settings
- Get auto reply settings
- Update auto reply settings
- Get MailTips (preview)
- Get attachments
- Create attachments
- Delete attachments
Folder operations
Mailbox folders can contain messages and other folders. You can get, create, change, delete, and manage folders. You can use the following well-known folder names instead of the ID to specify the corresponding folder: Inbox, SentItems, Drafts, or DeletedItems.
See also
Use the Mail REST API
Authentication
Like other Outlook REST API, for every request to the Mail API, you should include a valid access token. Getting an access token requires you to have registered and identified your app, and obtained the appropriate authorization.
You can find out more about some streamlined registration and authorization options for you. Keep this in mind as you proceed with the specific operations in the Mail API.
Version of API
The Mail REST API is supported in all versions of the Outlook REST API. The functionality may differ depending on the specific version.
Target user
All Mail API requests are performed on behalf of the signed-in user unless specified. A few API subsets, such as Focused Inbox API, can be performed on the signed-in user, or a user specified by a user ID, given the appropriate permissions.
See Use the Outlook REST API for more information common to all subsets of the Outlook REST API.
Get messages
You can get a message collection or an individual message from a mailbox folder.
Each message in the response contains multiple properties, including the Body property. The message body can be either text or HTML. If the body is HTML, by default, any potentially unsafe HTML (for example, JavaScript) embedded in the Body property would be removed before the body content is returned in a REST response.
To get the entire, original HTML content, include the following HTTP request header:
Prefer: outlook.allow-unsafe-html
To specify the desired format to be returned in the Body and UniqueBody properties in a GET request, use
the Prefer: outlook.body-content-type header:
- Specify
Prefer: outlook.body-content-type="text"to get a message body returned in text format. - Specify
Prefer: outlook.body-content-type="html", or just skip the header, to return the message body in HTML format.
If you specify either header, the response will include the corresponding Preference-Applied header as confirmation:
- For text format requests:
Preference-Applied: outlook.body-content-type="text" - For HTML format requests:
Preference-Applied: outlook.body-content-type="html"
Get a message collection
Minimum required scope
One of the following:
Note
The behavior of the operations in this section vary by version. Find out more by choosing a version under Office 365 REST API reference in the table of contents on the left.
Get a message collection from the entire mailbox of the signed-in user (including the Deleted Items and Clutter folders).
GET https://outlook.office.com/api/beta/me/messages
You can also specify a folder in the user's mailbox and get the message collection from that folder.
GET https://outlook.office.com/api/beta/me/MailFolders/{folder_id}/messages
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| folder_id | string | The folder ID, or the Inbox, Drafts, SentItems, or DeletedItems well-known folder name, if you're getting messages from a specific folder. Specifying AllItems would return all messages from the entire mailbox |
Note
By default, each message in the response includes all its properties. Use $select to specify only those properties you need for best performance. The Id property is always returned. See OData query parameters for filtering, sorting, and paging parameters.
The following example shows how to use $select to specify returning only the Sender and Subject properties of each message in the response. Refer to the sample response in Get a message for a full list of properties that would be returned for a message if you don't use $select.
Sample request
GET https://outlook.office.com/api/beta/me/MailFolders/sentitems/messages/?$select=Sender,Subject
Sample response
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/MailFolders('sentitems')/Messages(Sender,Subject)",
"value": [
{
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGI2TIzAAAA=')",
"@odata.etag": "W/\"CQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTJqS\"",
"Id": "AAMkAGI2TIzAAAA=",
"Subject": "Meeting Notes",
"Sender": {
"EmailAddress": {
"Name": "Alex D",
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com"
}
}
},
{
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGI2TIy-AAA=')",
"@odata.etag": "W/\"CQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTJqP\"",
"Id": "AAMkAGI2TIy-AAA=",
"Subject": "Contract Signing",
"Sender": {
"EmailAddress": {
"Name": "Alex D",
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com"
}
}
},
{
"@odata.type": "#Microsoft.OutlookServices.EventMessage",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGI2TIy9AAA=')",
"@odata.etag": "W/\"CwAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTJqJ\"",
"Id": "AAMkAGI2TIy9AAA=",
"Subject": "Rob:Alex 1:1",
"Sender": {
"EmailAddress": {
"Name": "Alex D",
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com"
}
}
}
]
}
Response type
The requested message collection.
Get a message
Minimum required scope
One of the following:
Get a message by ID.
GET https://outlook.office.com/api/beta/me/messages/{message_id}
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | string | The message ID. |
Sample request
GET https://outlook.office.com/api/beta/me/messages/AAMkAGI2THVSAAA=
Sample response
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGI2THVSAAA=')",
"@odata.etag": "W/\"CQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIKz\"",
"Id": "AAMkAGI2THVSAAA=",
"CreatedDateTime": "2014-10-20T00:41:57Z",
"LastModifiedDateTime": "2014-10-20T00:41:57Z",
"ChangeKey": "CQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIKz",
"InternetMessageId": "SN2PR00M@SN2.namprd00.prod.outlook.com",
"Categories": [],
"ReceivedDateTime": "2014-10-20T00:41:57Z",
"SentDateTime": "2014-10-20T00:41:53Z",
"HasAttachments": true,
"Subject": "Re: Meeting Notes",
"Body": {
"ContentType": "Text",
"Content": "\n________________________________________\nFrom: Alex D\nSent: Sunday, October 19, 2014 5:28 PM\nTo: Katie Jordan\nSubject: Meeting Notes\n\nPlease send me the meeting notes ASAP\n"
},
"BodyPreview": "________________________________________\nFrom: Alex D\nSent: Sunday, October 19, 2014 5:28 PM\nTo: Katie Jordan\nSubject: Meeting Notes\n\nPlease send me the meeting notes ASAP",
"Importance": "Normal",
"ParentFolderId": "AAMkAGI2AAEMAAA=",
"Sender": {
"EmailAddress": {
"Name": "Katie Jordan",
"Address": "katiej@a830edad9050849NDA1.onmicrosoft.com"
}
},
"From": {
"EmailAddress": {
"Name": "Katie Jordan",
"Address": "katiej@a830edad9050849NDA1.onmicrosoft.com"
}
},
"ToRecipients": [
{
"EmailAddress": {
"Name": "Alex D",
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com"
}
}
],
"CcRecipients": [],
"BccRecipients": [],
"ReplyTo": [],
"ConversationId": "AAQkAGI2yEto=",
"ConversationIndex": "AQHRh3zqrkAcds2kw==",
"IsDeliveryReceiptRequested": false,
"IsReadReceiptRequested": false,
"IsRead": false,
"IsDraft": false,
"WebLink": "https://outlook.office365.com/owa/?ItemID=AAMkAGI2THVSAAA%3D&exvsurl=1&viewmodel=ReadMessageItem"
}
Response type
The requested message.
Note
By default, the response includes all the properties of the specified message. Use $select to specify only those properties you need for best performance. The Id property is always returned. See OData query parameters for filtering, sorting, and paging parameters.
The following example shows how to use $select to specify returning only the Sender and Subject properties of the message in the response.
GET https://outlook.office.com/api/beta/me/messages/AAMkAGE1I5MTAAA=?$select=Sender,Subject
Synchronize messages
Minimum required scope
One of the following:
You can synchronize your local data store with the messages on the server. Message synchronization is a per-folder operation, for example, you can synchronize all of the messages in your Inbox. To synchronize the messages in a folder hierarchy you need to synchronize each folder individually.
The API supports both full synchronization that retrieves all of the messages in a folder, and incremental synchronization that retrieves all of the messages that have changed since the last full synchronization.
Synchronizing a mail folder typically requires two or more GET requests. You make the GET request much like the way you get messages, except that you include certain request headers, and a deltaToken or skipToken when appropriate.
Request headers
You must specify the Prefer: odata.track-changes header in all sync requests, except those that include a
skipTokenthat is returned from a previous sync request. In the first response, look for the Preference-Applied: odata.track-changes header to confirm that the resource supports synchronizing before proceeding.You may specify the Prefer: odata.maxpagesize={x} header to set the maximum number of messages returned in a request.
This is a full message synchronization round:
Make the initial GET request with the mandatory Prefer: odata.track-changes header. The initial response to a sync request always returns a deltaToken. (The second and subsequent GET requests differ from the first GET request by including either a deltaToken or a skipToken received in a previous response.)
If the first response returns the Preference-Applied: odata.track-changes header, you can proceed with synchronizing the folder.
Make a second GET request. Specify the Prefer: odata.track-changes header and the deltaToken returned from the first GET to determine if there are any additional messages. The second request will return additional messages, and either a skipToken if there are more messages available, or a deltaToken if the last message has been synchronized, in which case the synchronization round is complete and you can stop.
Continue synchronizing by sending a GET call and including a skipToken that's returned from the previous call. Stop when you get a final response that contains an @odata.deltaLink header with a deltaToken again, which indicates the sync is complete.
Cache the last delta token received in the full synchronization round. Use it to start an incremental synchronization round.
This is an incremental synchronization round:
Make the initial GET request with the mandatory Prefer: odata.track-changes header and the cached deltaToken received in the last response of a full synchronization round.
The second and subsequent steps follow the pattern used for a full synchronization.
To sync messages in a specific folder
Initial request
GET https://outlook.office365.com/api/beta/me/MailFolders('{folder_id}')/messages
Second request, or first request of a subsequent round
GET https://outlook.office365.com/api/beta/me/MailFolders('{folder_id}')/messages/?$deltaToken={delta_token}
Third or subsequent request in the same round
Continue to send the next sync request if the previous response includes a skipToken. Stop when you get a response that contains an @odata.deltaLink header with a deltaToken again.
GET https://outlook.office365.com/api/beta/me/MailFolders('{folder_id}')/messages/?$skipToken={skip_token}
| Parameters | Type | Description |
|---|---|---|
| Header parameters | ||
| Prefer | odata.track-changes | Indicates that the request is a synchronization request. Required for the first 2 GET requests in a round. |
| Prefer | odata.maxpagesize | Sets the number of messages to be returned in each response. Optional. |
| URL parameters | ||
| folder_id | string | The folder ID, or the Inbox, Drafts, SentItems, or DeletedItems well-known folder name to synchronize. Required. |
| deltaToken | String | The token that identifies the last sync request for that folder. It is returned as part of the value for @odata.deltaLink in that previous sync response. Required for the second GET request. |
| skipToken | String | The token that indicates that there are more messages to download. Required if it is returned as part of the value for @odata.nextLink in the previous sync response. |
By default synchronization returns all of the properties and all of the messages in a folder. Use a $select query expression to specify only the properties that your need for best performance. The Id property is always returned.
Synchronization supports the query expressions $select, $top, $expand. There is limited support for $filter and $orderby, and no support for $search.
- The only supported $filter expresssions are “$filter=ReceivedDateTime+ge+{value}” or “$filter=ReceivedDateTime+gt+{value}".
- The only supported $orderby expression is “$orderby=ReceivedDateTime+desc”. If you do not include an $orderby expression, the return order is not guaranteed.
See OData query parameters for filtering, sorting, and paging parameters.
Response type
A collection containing the requested messages, and a deltaToken or skipToken that you use to request additional pages of message data from server for an incremental synchronization.
Example
The following example shows a series of requests to synchronize a specific folder which contains 7 messages. The first sync request specifies returning 2 messages at a time (odata.maxpagesize is 2), and only the Sender and Subject properties for each message.
- The initial response returns 2 messages, a
deltaLinkanddeltaToken. - The second request uses that
deltaToken. The second response returns 2 messages, anextLinkandskipToken. - To complete the sync, the third and fourth requests use the
skipTokenreturned from the previous sync request, until the fourth sync response returns adeltaLinkanddeltaToken, in which case this round of sync is complete. Save thedeltaTokenfor the next round of sync.
Sample initial request
GET https://outlook.office.com/api/beta/Me/MailFolders('AAMkAGI5MAAAwW-j-AAA=')/messages?$select=Subject,Sender HTTP/1.1
Prefer: odata.maxpagesize=2
Prefer: odata.track-changes
Sample initial response data
The initial response includes a Preference-Applied: odata.track-changes header, indicating that this folder supports synchronization. The response also includes two messages and a deltaToken.
Preference-Applied: odata.track-changes
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/MailFolders('AAMkAGI5MAAAwW-j-AAA%3D')/Messages(Subject,Sender)",
"value":[
{
"@odata.id":"https://outlook.office.com/api/beta/Users('f97adce1-d718-4a0e-9af8-b10167e3a346@0d76cf04-f6a0-46cc-947b-d2e1bdd98d11')/Messages('AAMkAGI5MAAAwXADPAAA=')",
"@odata.etag":"W/\"CQAAABYAAAA+Z5tnXBgBRpOasqS9T0shAAAwYS9+\"",
"Id":"AAMkAGI5MAAAwXADPAAA=",
"Subject":"Updates from All Company",
"Sender":{
"EmailAddress":{
"Name":"Contoso Demo on Yammer",
"Address":"noreply@yammer.com"
}
}
},
{
"@odata.id":"https://outlook.office.com/api/beta/Users('f97adce1-d718-4a0e-9af8-b10167e3a346@0d76cf04-f6a0-46cc-947b-d2e1bdd98d11')/Messages('AAMkAGI5MAAAwXADVAAA=')",
"@odata.etag":"W/\"CQAAABYAAAA+Z5tnXBgBRpOasqS9T0shAAAwYS+E\"",
"Id":"AAMkAGI5MAAAwXADVAAA=",
"Subject":"RE: Latin American Ad Campaign - XT Series",
"Sender":{
"EmailAddress":{
"Name":"Alex Darrow",
"Address":"AlexD@contoso.onmicrosoft.com"
}
}
}
],
"@odata.deltaLink":"https://outlook.office.com/api/beta/Me/MailFolders('AAMkAGI5MAAAwW-j-AAA=')/messages/?%24select=Subject%2cSender&%24deltatoken=MfzCBD5nm2dcGAFGk5qypL1PSyEAADFmX28BAAAA"
}
Sample second request
The second request specifies the deltaToken returned from the previous response.
GET https://outlook.office.com/api/beta/Me/MailFolders('AAMkAGI5MAAAwW-j-AAA=')/messages/?%24select=Subject%2cSender&%24deltatoken=MfzCBD5nm2dcGAFGk5qypL1PSyEAADFmX28BAAAA HTTP/1.1
Prefer: odata.maxpagesize=2
Prefer: odata.track-changes
Sample second response data
The second response includes two more messages and a skipToken, indicating there are more messages to sync in the folder.
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/MailFolders('AAMkAGI5MAAAwW-j-AAA%3D')/Messages(Subject,Sender)/$delta",
"value":[
{
"@odata.id":"https://outlook.office.com/api/beta/Users('f97adce1-d718-4a0e-9af8-b10167e3a346@0d76cf04-f6a0-46cc-947b-d2e1bdd98d11')/Messages('AAMkAGI5MAAAwXADQAAA=')",
"@odata.etag":"W/\"CQAAABYAAAA+Z5tnXBgBRpOasqS9T0shAAAwYS9/\"",
"Id":"AAMkAGI5MAAAwXADQAAA=",
"Subject":"International Launch Planning for XT2000",
"Sender":{
"EmailAddress":{
"Name":"Engineering",
"Address":"engineering@contoso.onmicrosoft.com"
}
}
},
{
"@odata.id":"https://outlook.office.com/api/beta/Users('f97adce1-d718-4a0e-9af8-b10167e3a346@0d76cf04-f6a0-46cc-947b-d2e1bdd98d11')/Messages('AAMkAGI5MAAAwXADUAAA=')",
"@odata.etag":"W/\"CQAAABYAAAA+Z5tnXBgBRpOasqS9T0shAAAwYS+D\"",
"Id":"AAMkAGI5MAAAwXADUAAA=",
"Subject":"RE: Latin American Ad Campaign - XT Series",
"Sender":{
"EmailAddress":{
"Name":"Anne Wallace",
"Address":"AnneW@contoso.onmicrosoft.com"
}
}
}
],
"@odata.nextLink":"https://outlook.office.com/api/beta/Me/MailFolders('AAMkAGI5MAAAwW-j-AAA=')/messages/?%24select=Subject%2cSender&%24skipToken=MfzCAj5nm2dcGAFGk5qypL1PSyEAADFmX28CAAAA"
}
Sample third request
The third request includes the skipToken returned from the previous response.
GET https://outlook.office.com/api/beta/Me/MailFolders('AAMkAGI5MAAAwW-j-AAA=')/messages/?%24select=Subject%2cSender&%24skipToken=MfzCAj5nm2dcGAFGk5qypL1PSyEAADFmX28CAAAA HTTP/1.1
Prefer: odata.maxpagesize=2
Sample third response data
The third response returns two more messages and another skipToken, indicating there are still messages in the folder to sync.
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/MailFolders('AAMkAGI5MAAAwW-j-AAA%3D')/Messages(Subject,Sender)/$delta",
"value":[
{
"@odata.id":"https://outlook.office.com/api/beta/Users('f97adce1-d718-4a0e-9af8-b10167e3a346@0d76cf04-f6a0-46cc-947b-d2e1bdd98d11')/Messages('AAMkAGI5MAAAwXADTAAA=')",
"@odata.etag":"W/\"CQAAABYAAAA+Z5tnXBgBRpOasqS9T0shAAAwYS+C\"",
"Id":"AAMkAGI5MAAAwXADTAAA=",
"Subject":"RE: Latin American Ad Campaign - XT Series",
"Sender":{
"EmailAddress":{
"Name":"Pavel Bansky",
"Address":"PavelB@contoso.onmicrosoft.com"
}
}
},
{
"@odata.id":"https://outlook.office.com/api/beta/Users('f97adce1-d718-4a0e-9af8-b10167e3a346@0d76cf04-f6a0-46cc-947b-d2e1bdd98d11')/Messages('AAMkAGI5MAAAwXADSAAA=')",
"@odata.etag":"W/\"CQAAABYAAAA+Z5tnXBgBRpOasqS9T0shAAAwYS+B\"",
"Id":"AAMkAGI5MAAAwXADSAAA=",
"Subject":"Latin American Ad Campaign - XT Series",
"Sender":{
"EmailAddress":{
"Name":"Engineering",
"Address":"engineering@contoso.onmicrosoft.com"
}
}
}
],
"@odata.nextLink":"https://outlook.office.com/api/beta/Me/MailFolders('AAMkAGI5MAAAwW-j-AAA=')/messages/?%24select=Subject%2cSender&%24skipToken=MfzCAj5nm2dcGAFGk5qypL1PSyEAADFmX28DAAAA"
}
Sample fourth request
The fourth request includes the skipToken from the previous response.
GET https://outlook.office.com/api/beta/Me/MailFolders('AAMkAGI5MAAAwW-j-AAA=')/messages/?%24select=Subject%2cSender&%24skipToken=MfzCAj5nm2dcGAFGk5qypL1PSyEAADFmX28DAAAA HTTP/1.1
Prefer: odata.maxpagesize=2
Sample fourth and final response data
The fourth response returns the only remaining message in the folder, and a deltaToken which indicates
synchronization is complete for this folder. Save the deltaToken for the next round of sync for this folder.
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/MailFolders('AAMkAGI5MAAAwW-j-AAA%3D')/Messages(Subject,Sender)/$delta",
"value":[
{
"@odata.id":"https://outlook.office.com/api/beta/Users('f97adce1-d718-4a0e-9af8-b10167e3a346@0d76cf04-f6a0-46cc-947b-d2e1bdd98d11')/Messages('AAMkAGI5MAAAwXADRAAA=')",
"@odata.etag":"W/\"CQAAABYAAAA+Z5tnXBgBRpOasqS9T0shAAAwYS+A\"",
"Id":"AAMkAGI5MAAAwXADRAAA=",
"Subject":"Data sheets for the XT2000 ",
"Sender":{
"EmailAddress":{
"Name":"Engineering",
"Address":"engineering@contoso.onmicrosoft.com"
}
}
}
],
"@odata.deltaLink": "https://outlook.office365.com/api/beta/Me/MailFolders('AAMkAGI5MAAAwW-j-AAA=')/messages/?%24deltaToken=0_zCBD5nm2dcGAFGk5qypL1PSyEAADBb9RkEAAAA"
}
Sample incremental synchronization request
The first request includes the deltaToken from the last full synchronization response.
GET https://outlook.office.com/api/beta/Me/MailFolders('AAMkAGI5MAAAwW-j-AAA=')/messages/?%24select=Subject%2cSender&%24deltatoken=0_zCBD5nm2dcGAFGk5qypL1PSyEAADBb9RkEAAAA HTTP/1.1
Prefer: odata.maxpagesize=2
Prefer: odata.track-changes
The response to the incremental synchronization request includes any changes to the folder message set.
Sample incremental synchronization response
The response shows that one change has been made to the message set. A message is deleted.
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/MailFolders('AAMkAGI5MAAAwW-j-AAA%3D')/Messages(Subject,Sender)/$delta",
"value": [
{
"id": "Messages('AAMkAGY5MDFjNTQyLWI3NzItNGE4My04ZWE4LWQ4YmMwNTJkYTg1YwBGAAAAAAD7fYH1FVR1TayS78jtGGehBwDB1GgBNTpbT6Qe-PzdAR4YAh7cdimCAADwOTzPjXdMTKEex95TwbKkAACLEykWAAA=')",
"reason": "deleted"
}
]
,
"@odata.deltaLink": "https://outlook.office365.com/api/beta/Me/MailFolders('AAMkAGI5MAAAwW-j-AAA=')/messages/?%24deltaToken=4_zRDV5nm2dcGAFGk5qypL1PSyEAADBb9RkEAAAA"
}
Create and send messages
You can send a new message on the fly, or create a draft message and then send it. You can create drafts in any folder.
Send a new message on the fly
Minimum required scope
One of the following:
Send the message supplied in the request body by using the SendMail method. You can include one or more attachments in the same action call by specifying them in the Attachments collection property. You can also save the message in the Sent Items folder.
POST https://outlook.office.com/api/beta/me/sendmail
| Required parameter | Type | Description |
|---|---|---|
| Body parameters | ||
| Message | Message | The message to send. |
| SavetoSentItems | boolean | Indicates whether to save the message in Sent Items. Default is true. |
Specify the Message parameter with the required ToRecipients property and any writable message properties in the request body. The SaveToSentItems parameter is required only if false.
Sample request
POST https://outlook.office.com/api/beta/me/sendmail
Content-Type: application/json
{
"Message": {
"Subject": "Meet for lunch?",
"Body": {
"ContentType": "Text",
"Content": "The new cafeteria is open."
},
"ToRecipients": [
{
"EmailAddress": {
"Address": "garthf@a830edad9050849NDA1.onmicrosoft.com"
}
}
],
"Attachments": [
{
"@odata.type": "#Microsoft.OutlookServices.FileAttachment",
"Name": "menu.txt",
"ContentBytes": "bWFjIGFuZCBjaGVlc2UgdG9kYXk="
}
]
},
"SaveToSentItems": "false"
}
Sample response
Status code: 202
Create a draft message
Minimum required scope
One of the following:
Create a draft of a new message. Drafts can be created in any folder and optionally updated before sending. To save to the Drafts folder, use the /me/messages shortcut.
POST https://outlook.office.com/api/beta/me/messages
POST https://outlook.office.com/api/beta/me/MailFolders/{folder_id}/messages
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| folder_id | string | The destination folder ID, or the Inbox or Drafts well-known folder name. |
Specify any writable message properties in the request body.
Sample request
POST https://outlook.office.com/api/beta/me/MailFolders/inbox/messages
Content-Type: application/json
{
"Subject": "Did you see last night's game?",
"Importance": "Low",
"Body": {
"ContentType": "HTML",
"Content": "They were <b>awesome</b>!"
},
"ToRecipients": [
{
"EmailAddress": {
"Address": "katiej@a830edad9050849NDA1.onmicrosoft.com"
}
}
]
}
Sample response
Status code: 201
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGE0Mz7k0AAA=')",
"@odata.etag": "W/\"CQAAABYAAAAmP1Ln1wcHRariNdTMGAO9AAAS0Ag5\"",
"Id": "AAMkAGE0Mz7k0AAA=",
"ChangeKey": "CQAAABYAAAAmP1Ln1wcHRariNdTMGAO9AAAS0Ag5",
"Categories": [],
"InternetMessageId": "SN2PR00M@SN2.namprd00.prod.outlook.com",
"CreatedDateTime": "2014-10-18T20:06:51Z",
"LastModifiedDateTime": "2014-10-18T20:06:51Z",
"Subject": "Did you see last night's game?",
"BodyPreview": "They were awesome!",
"Body": {
"ContentType": "HTML",
"Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n</head>\r\n<body>\r\nThey were <b>awesome</b>!\r\n</body>\r\n</html>\r\n"
},
"Importance": "Low",
"HasAttachments": false,
"ParentFolderId": "AAMkAGE0MAAEPAAA=",
"From": null,
"Sender": null,
"ToRecipients": [
{
"EmailAddress": {
"Address": "katiej@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Katie Jordan"
}
}
],
"CcRecipients": [],
"BccRecipients": [],
"ReplyTo": [],
"ConversationId": "AAQkAGE0Mpv2hisc=",
"ConversationIndex": "AQHRf4zqrkAcds2kw==",
"ReceivedDateTime": "2014-10-18T20:06:51Z",
"SentDateTime": "2014-10-18T20:06:51Z",
"IsDeliveryReceiptRequested": false,
"IsReadReceiptRequested": false,
"IsDraft": true,
"IsRead": true
}
Response type
The draft message.
Send a draft message
Minimum required scope
One of the following:
Send a new message draft, a Reply draft, a Reply All draft, or a Forward draft by using the Send method. The message is then saved in the Sent Items folder.
POST https://outlook.office.com/api/beta/me/messages/{message_id}/send
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | string | The ID of the draft message to send. |
Sample request
POST https://outlook.office.com/api/beta/me/messages/AAMkAGE0Mz7k0AAA=/send
Sample response
Status code: 202
Reply or reply all to messages
Note
The behavior of the operations in this section vary by version. Find out more by choosing a version under Office 365 REST API reference in the table of contents on the left.
You can reply to a message, add a comment or update message properties all in one call, or you can first create a reply draft and update any message properties in one call, then send the draft.
You can reply to only the sender of the message or reply to all recipients at once.
- Reply to sender on the fly
- Reply all on the fly
- Create a draft reply message
- Create a draft reply-all message
Reply to sender on the fly
Minimum required scope
One of the following:
Reply to the sender of a message, add a comment or modify any updateable properties all in one Reply call. The message is then saved in the Sent Items folder.
Alternatively, you can first create a draft reply message to include a comment or update any message properties, and then send the reply.
POST https://outlook.office.com/api/beta/me/messages/{message_id}/reply
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | string | The ID of the message to reply to. |
| Body parameters | ||
| Comment | string | A comment to include. Can be an empty string. |
| Message | Message | Any writeable properties to update in the reply message. |
Note
- You can specify either a comment or the Body property of the
Messageparameter. Specifying both will return an HTTP 400 Bad Request error. - If ReplyTo is specified in the original message, per Internet Message Format (RFC 2822), you should send the reply to the recipients in ReplyTo and not the recipient in From.
Sample request
The following example includes a comment and adds a recipient to the reply message.
POST https://outlook.office.com/api/beta/me/messages/AAMkADA1MTAAAAqldOAAA=/reply
Content-Type: application/json
{
"Message":{
"ToRecipients":[
{
"EmailAddress": {
"Address":"fannyd@contoso.onmicrosoft.com",
"Name":"Fanny Downs"
}
},
{
"EmailAddress":{
"Address":"randiw@contoso.onmicrosoft.com",
"Name":"Randi Welch"
}
}
]
},
"Comment": "Fanny, Randi, would you name the group please?"
}
Sample response
Status code: 202
Reply all on the fly
Minimum required scope
One of the following:
Reply to all recipients of a message by specifying a comment and modifying any updateable properties for the reply, all by using the ReplyAll method. The message is then saved in the Sent Items folder.
Alternatively, you can first create a draft reply-all message to include a comment and update any message properties, and then send the reply.
POST https://outlook.office.com/api/beta/me/messages/{message_id}/replyall
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | string | The ID of the message to reply to. |
| Body parameters | ||
| Comment | string | A comment to include. Can be an empty string. |
| Message | Message | Any writeable properties to update in the reply-all message. |
Note
- You can specify either a comment or the Body property of the
Messageparameter. Specifying both will return an HTTP 400 Bad Request error. - If ReplyTo is specified in the original message, per Internet Message Format (RFC 2822), you should send the reply to the recipients in ReplyTo and ToRecipients, and not the recipients in From and ToRecipients.
Sample request
The following example includes a comment and adds an attachment to the reply-all message.
POST https://outlook.office.com/api/beta/me/messages/AAMkADA1MTAAAH5JaKAAA=/ReplyAll
Content-Type: application/json
{
"Message":{
"Attachments": [
{
"@odata.type": "#Microsoft.OutlookServices.FileAttachment",
"Name": "guidelines.txt",
"ContentBytes": "bWFjIGFuZCBjaGVlc2UgdG9kYXk="
}
]
},
"Comment": "Please take a look at the attached guidelines before you decide on the name."
}
Sample response
Status code: 202
Create a draft reply message
Minimum required scope
One of the following:
Create a draft of the reply message to include a comment or update any message properties all in one CreateReply call. You can then send the draft message.
POST https://outlook.office.com/api/beta/me/messages/{message_id}/createreply
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | string | The ID of the message to reply to. |
| Body parameters | ||
| Comment | string | A comment to include. Can be an empty string. |
| Message | Message | Any writeable properties to update in the reply message. |
Note
- You can specify either a comment or the Body property of the
Messageparameter. Specifying both will return an HTTP 400 Bad Request error. - If ReplyTo is specified in the original message, per Internet Message Format (RFC 2822), you should send the reply to the recipients in ReplyTo, and not the recipients in From.
Sample request
The following example creates a reply draft, adds a comment and a recipient in the request body.
POST https://outlook.office.com/api/beta/me/messages/AAMkADA1MTAAAAqldOAAA=/createreply
Content-Type: application/json
{
"Message":{
"ToRecipients":[
{
"EmailAddress": {
"Address":"fannyd@contoso.onmicrosoft.com",
"Name":"Fanny Downs"
}
}
]
},
"Comment": "Fanny, would you name the group if the project is approved, please?"
}
Sample response
Status code: 201
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('86b6ceaf-57f7-4278-97c4-4da0a97f6cdb@70559e59-b378-49ea-8e53-07a3a3d27f5b')/Messages('AAMkADA1MTAAAH5JKoAAA=')",
"@odata.etag": "W/\"CQAAABYAAADX8oL1Wa7jQbcPAHouCzswAAAH5/DO\"",
"Id": "AAMkADA1MTAAAH5JKoAAA=",
"CreatedDateTime": "2016-03-15T08:33:43Z",
"LastModifiedDateTime": "2016-03-15T08:33:43Z",
"ChangeKey": "CQAAABYAAADX8oL1Wa7jQbcPAHouCzswAAAH5/DO",
"Categories": [ ],
"ReceivedDateTime": "2016-03-15T08:33:43Z",
"SentDateTime": "2016-03-15T08:33:43Z",
"HasAttachments": false,
"InternetMessageId": "<DM2PR00MB00571796B16132601E1F286CF7890@DM2PR00MB0057.namprd00.prod.outlook.com>",
"Subject": "RE: Let's start a group",
"Body": {
"ContentType": "HTML",
"Content": "<html>\r\n<body>Fanny, would you name the group if the project is approved, please?\r\n<b>From:</b> Fanny Downs<br>\r\n<b>Sent:</b> Friday, March 4, 2016 12:23:35 AM<br>\r\n<b>To:</b> Admin<br>\r\n<b>Subject:</b> Re: Let's start a group</font>\r\n<p>That's a great idea!<br>\r\n</body>\r\n</html>"
},
"BodyPreview": "Fanny, would you name the group if the project is approved, please?\r\n________________________________\r\nFrom: Fanny Downs\r\nSent: Friday, March 4, 2016 12:23:35 AM\r\nTo: Admin\r\nSubject: Re: Let's start a group\r\n\r\n\r\nThat's a gre",
"Importance": "Normal",
"ParentFolderId": "AQMkADA1MTAAAAIBDwAAAA==",
"Sender": {
"EmailAddress": {
"Name": "Admin",
"Address": "admin@contoso.onmicrosoft.com"
}
},
"From": null,
"ToRecipients": [
{
"EmailAddress": {
"Name": "Fanny Downs",
"Address": "fannyd@contoso.onmicrosoft.com"
}
}
],
"CcRecipients": [ ],
"BccRecipients": [ ],
"ReplyTo": [ ],
"ConversationId": "AAQkADA1MTVGjIwpLvWmGtIo-aFE=",
"ConversationIndex": "AQHRdar6akFxUaMjCku9aYa0ij9oUZ9IbLr7gBHStBQ=",
"IsDeliveryReceiptRequested": false,
"IsReadReceiptRequested": false,
"IsRead": true,
"IsDraft": true,
"WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADA1MTAAAH5JKoAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
"MentionedMe": null,
"AppliedHashtagsPreview": null,
"LikesPreview": null,
"MentionsPreview": null,
"Mentioned": [ ],
"InferenceClassification": "Focused",
"UnsubscribeData": [ ],
"UnsubscribeEnabled": false,
"Flag": { "FlagStatus": "NotFlagged" }
}
Response type
The draft Reply message with the ToRecipient, IsDraft, and other appropriate properties prepopulated.
Create a draft reply-all message
Minimum required scope
One of the following:
Create a draft of the reply-all message to include a comment or update any message properties, all in one CreateReplyAll call. You can then send the draft message.
POST https://outlook.office.com/api/beta/me/messages/{message_id}/createreplyall
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | string | The ID of the message to reply-all to. |
| Body parameters | ||
| Comment | string | A comment to include. Can be an empty string. |
| Message | Message | Any writeable properties to update in the reply-all message. |
Note
- You can specify either a comment or the Body property of the
Messageparameter. Specifying both will return an HTTP 400 Bad Request error. - If ReplyTo is specified in the original message, per Internet Message Format (RFC 2822), you should send the reply to the recipients in the ReplyTo and ToRecipients properties, and not the recipients in the From and ToRecipients properties.
Sample request
The following example creates a draft to reply all, and adds an attachment and comment all in one CreateReplyAll call.
POST https://outlook.office.com/api/beta/me/messages/AAMkADA1MTAAAH5JaKAAA=/createreplyall
Content-Type: application/json
{
"Message":{
"Attachments": [
{
"@odata.type": "#Microsoft.OutlookServices.FileAttachment",
"Name": "guidelines.txt",
"ContentBytes": "bWFjIGFuZCBjaGVlc2UgdG9kYXk="
}
]
},
"Comment": "if the project gets approved, please take a look at the attached guidelines before you decide on the name."
}
Sample response
Status code: 201
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('86b6ceaf-57f7-4278-97c4-4da0a97f6cdb@70559e59-b378-49ea-8e53-07a3a3d27f5b')/Messages('AAMkADA1MTAAAH5JKpAAA=')",
"@odata.etag": "W/\"CQAAABYAAADX8oL1Wa7jQbcPAHouCzswAAAH5/DP\"",
"Id": "AAMkADA1MTAAAH5JKpAAA=",
"CreatedDateTime": "2016-03-15T08:37:34Z",
"LastModifiedDateTime": "2016-03-15T08:37:34Z",
"ChangeKey": "CQAAABYAAADX8oL1Wa7jQbcPAHouCzswAAAH5/DP",
"Categories": [ ],
"ReceivedDateTime": "2016-03-15T08:37:34Z",
"SentDateTime": "2016-03-15T08:37:34Z",
"HasAttachments": true,
"InternetMessageId": "<DM2PR00MB005732BE05BD669AC7CE056EF7890@DM2PR00MB0057.namprd00.prod.outlook.com>",
"Subject": "RE: Let's start a group",
"Body": {
"ContentType": "HTML",
"Content": "<html>\r\n<body dir=\"ltr\">\r\nif the project gets approved, please take a look at the attached guidelines before you decide on the name.\r\n<b>From:</b> Admin<br>\r\n<b>Sent:</b> Tuesday, March 15, 2016 6:36:32 AM<br>\r\n<b>To:</b> Fanny Downs; Randi Welch<br>\r\n<b>Subject:</b> RE: Let's start a group\r\n<div>Fanny, Randi, would you name the group please?\r\n<b>From:</b> Fanny Downs<br>\r\n<b>Sent:</b> Friday, March 4, 2016 12:23:35 AM<br>\r\n<b>To:</b> Admin<br>\r\n<b>Subject:</b> Re: Let's start a group</font>\r\n</body>\r\n</html>"
},
"BodyPreview": "if the project gets approved, please take a look at the attached guidelines before you decide on the name.\r\n________________________________\r\nFrom: Admin\r\nSent: Tuesday, March 15, 2016 6:36:32 AM\r\nTo: Fanny Downs; Randi Welch\r\nSubj",
"Importance": "Normal",
"ParentFolderId": "AQMkADA1MTAAAAIBDwAAAA==",
"Sender": {
"EmailAddress": {
"Name": "Admin",
"Address": "admin@contoso.onmicrosoft.com"
}
},
"From": null,
"ToRecipients": [
{
"EmailAddress": {
"Name": "Fanny Downs",
"Address": "fannyd@contoso.onmicrosoft.com"
}
},
{
"EmailAddress": {
"Name": "Randi Welch",
"Address": "randiw@contoso.onmicrosoft.com"
}
}
],
"CcRecipients": [ ],
"BccRecipients": [ ],
"ReplyTo": [ ],
"ConversationId": "AAQkADA1MTLvWmGtIo-aFE=",
"ConversationIndex": "AQHRdar6akFxUaMjCku9aYa0ij9oUZ9IbLr7gBGx9qGAACHRQA==",
"IsDeliveryReceiptRequested": false,
"IsReadReceiptRequested": false,
"IsRead": true,
"IsDraft": true,
"WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADA1MTAAAH5JKpAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
"MentionedMe": null,
"AppliedHashtagsPreview": null,
"LikesPreview": null,
"MentionsPreview": null,
"Mentioned": [ ],
"InferenceClassification": "Focused",
"UnsubscribeData": [ ],
"UnsubscribeEnabled": false,
"Flag": { "FlagStatus": "NotFlagged" }
}
Response type
The draft Reply All message with the ToRecipient, IsDraft, and other appropriate properties prepopulated.
Forward new or drafted messages
Note
The behavior of the operations in this section vary by version. Find out more by choosing a version under Office 365 REST API reference in the table of contents on the left.
You can forward a message, add a comment or update message properties all in one call, or you can first create a draft and update any message properties in one call, and then send the draft.
Forward a message directly
Minimum required scope
One of the following:
Forward a message, add a comment or modify any updateable properties all in one Forward call. The message is then saved in the Sent Items folder.
Alternatively, you can first create a draft forward message to include a comment or update any message properties, and then send the draft message.
POST https://outlook.office.com/api/beta/me/messages/{message_id}/forward
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | string | The ID of the message to forward. |
| Body parameters | ||
| Comment | string | A comment to include. Can be an empty string. |
| ToRecipients | Collection(Recipient) | The list of recipients. |
| Message | Message | Any writeable properties to update in the reply message. |
Note
- You can specify either a comment or the Body property of the
Messageparameter. Specifying both will return an HTTP 400 Bad Request error. - You must specify either the
ToRecipientsparameter or the ToRecipients property of theMessageparameter. Specifying both or specifying neither will return an HTTP 400 Bad Request error.
Sample request
The following example sets the IsDeliveryReceiptRequested property to true, adds a comment and forwards the message.
POST https://outlook.office.com/api/beta/me/messages/AAMkADA1MTAAAH5JaLAAA=/forward
Content-Type: application/json
{
"Message":{
"IsDeliveryReceiptRequested": true,
"ToRecipients":[
{
"EmailAddress": {
"Address":"danas@contoso.onmicrosoft.com",
"Name":"Dana Swope"
}
}
]
},
"Comment": "Dana, just want to make sure you get this."
}
Sample response
Status code: 202
Create a draft forward message
Minimum required scope
One of the following:
Create a draft forward message to include a comment or update any message properties all in one CreateForward call. You can then send the draft message.
POST https://outlook.office.com/api/beta/me/messages/{message_id}/createforward
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | string | The ID of the message to forward. |
| Body parameters | ||
| Comment | string | A comment to include. Can be an empty string. |
| ToRecipients | Collection(Recipient) | The list of recipients. |
| Message | Message | Any writeable properties to update in the reply message. |
Note
- You can specify either a comment or the Body property of the
Messageparameter. Specifying both will return an HTTP 400 Bad Request error. - You must specify either the
ToRecipientsparameter or the ToRecipients property of theMessageparameter. Specifying both or specifying neither will return an HTTP 400 Bad Request error.
Sample request
POST https://outlook.office.com/api/beta/me/messages/AAMkADA1MTAAAH5JaLAAA=/createforward
Content-Type: application/json
{
"Message":{
"IsDeliveryReceiptRequested": true,
"ToRecipients":[
{
"EmailAddress": {
"Address":"danas@contoso.onmicrosoft.com",
"Name":"Dana Swope"
}
}
]
},
"Comment": "Dana, just want to make sure you get this; you'll need this if the project gets approved."
}
Sample response
Status code: 201
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('86b6ceaf-57f7-4278-97c4-4da0a97f6cdb@70559e59-b378-49ea-8e53-07a3a3d27f5b')/Messages('AAMkADA1MTAAAH5JKqAAA=')",
"@odata.etag": "W/\"CQAAABYAAADX8oL1Wa7jQbcPAHouCzswAAAH5/DQ\"",
"Id": "AAMkADA1MTAAAH5JKqAAA=",
"CreatedDateTime": "2016-03-15T08:42:10Z",
"LastModifiedDateTime": "2016-03-15T08:42:10Z",
"ChangeKey": "CQAAABYAAADX8oL1Wa7jQbcPAHouCzswAAAH5/DQ",
"Categories": [ ],
"ReceivedDateTime": "2016-03-15T08:42:10Z",
"SentDateTime": "2016-03-15T08:42:10Z",
"HasAttachments": true,
"InternetMessageId": "<DM2PR00MB0057E0EBC90EF37FC9233941F7890@DM2PR00MB0057.namprd00.prod.outlook.com>",
"Subject": "FW: Let's start a group",
"Body": {
"ContentType": "HTML",
"Content": "<html>\r\n<body>\r\nDana, just want to make sure you get this; you'll need this if the project gets approved.\r\n<b>From:</b> Admin<br>\r\n<b>Sent:</b> Tuesday, March 15, 2016 6:47:54 AM<br>\r\n<b>To:</b> Fanny Downs; Randi Welch<br>\r\n<b>Subject:</b> RE: Let's start a group</body>\r\n</html>\r\n"
},
"BodyPreview": "Dana, just want to make sure you get this; you'll need this if the project gets approved.\r\n________________________________\r\nFrom: Admin\r\nSent: Tuesday, March 15, 2016 6:47:54 AM\r\nTo: Fanny Downs; Randi Welch\r\nSubject: RE: Let's st",
"Importance": "Normal",
"ParentFolderId": "AQMkADA1MTAAAAIBDwAAAA==",
"Sender": {
"EmailAddress": {
"Name": "Admin",
"Address": "admin@contoso.onmicrosoft.com"
}
},
"From": null,
"ToRecipients": [
{
"EmailAddress": {
"Name": "Dana Swope",
"Address": "danas@contoso.onmicrosoft.com"
}
}
],
"CcRecipients": [ ],
"BccRecipients": [ ],
"ReplyTo": [ ],
"ConversationId": "AAQkADA1MTLvWmGtIo-aFE=",
"ConversationIndex": "AQHRdar6akFxUaMjCku9aYa0ij9oUZ9IbLr7gBGx9qGAAAMtlIAAH+3c",
"IsDeliveryReceiptRequested": true,
"IsReadReceiptRequested": false,
"IsRead": true,
"IsDraft": true,
"WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADA1MTAAAH5JKqAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
"MentionedMe": null,
"AppliedHashtagsPreview": null,
"LikesPreview": null,
"MentionsPreview": null,
"Mentioned": [ ],
"InferenceClassification": "Focused",
"UnsubscribeData": [ ],
"UnsubscribeEnabled": false,
"Flag": { "FlagStatus": "NotFlagged" }
}
Response type
The draft Forward message with IsDraft and appropriate properties prepopulated.
Update messages
Change writable properties on a message and save the changes.
Update a message
Minimum required scope
One of the following:
Change writable properties on a draft or existing message. Only the properties that you specify are changed.
PATCH https://outlook.office.com/api/beta/me/messages/{message_id}
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | string | The ID of the message to update. |
Specify one or more writable message properties in the request body.
Sample request
The following sample request sets two categories on a mail message and flags the message with a start and due date.
Note
If the FlagStatus is set to Flagged, the Flag.CompletedDate property must not be set.
PATCH https://outlook.office.com/api/beta/me/messages/AAMkAGE0Mz8S-AAA=
Content-Type: application/json
{
"Categories": [
"Orange category",
"Green category"
],
"IsRead": true,
"Flag": {
"FlagStatus": "Flagged",
DueDateTime": {
"DateTime": "2017-12-22T08:00:00.0000000",
"TimeZone": "UTC"
},
"StartDateTime": {
"DateTime": "2017-12-18T08:00:00.0000000",
"TimeZone": "UTC"
}
}
}
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGE0Mz8S-AAA=')",
"@odata.etag": "W/\"CQAAABYAAAAmP1Ln1wcHRariNdTMGAO9AAAS0AIP\"",
"Id": "AAMkAGE0Mz8S-AAA=",
"ChangeKey": "CQAAABYAAAAmP1Ln1wcHRariNdTMGAO9AAAS0AIP",
"InternetMessageId": "SN2PR00M@SN2.namprd00.prod.outlook.com",
"Categories": [
"Orange category",
"Green category"
],
"CreatedDateTime": "2014-10-17T17:12:15Z",
"LastModifiedDateTime": "2014-10-19T03:24:35Z",
"Subject": "Meeting notes from today",
"BodyPreview": "See attached",
"Body": {
"ContentType": "HTML",
"Content": "<html>\r\n...</html>\r\n"
},
"Importance": "Normal",
"HasAttachments": true,
"ParentFolderId": "AAMkAGE0MAAEMAAA=",
"From": {
"EmailAddress": {
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Alex D"
}
},
"Sender": {
"EmailAddress": {
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Alex D"
}
},
"ToRecipients": [
{
"EmailAddress": {
"Address": "katiej@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Katie Jordan"
}
}
],
"CcRecipients": [],
"BccRecipients": [],
"ReplyTo": [],
"ConversationId": "AAQkAGE0Mip-qvhs=",
"ConversationIndex": "AQHRh5tqrkAcds2kw==",
"ReceivedDateTime": "2014-10-17T17:12:15Z",
"SentDateTime": "2014-10-17T17:12:12Z",
"IsDeliveryReceiptRequested": false,
"IsReadReceiptRequested": false,
"IsDraft": false,
"IsRead": true,
"Flag": {
"FlagStatus": "Flagged",
"DueDateTime": {
"DateTime": "2017-12-22T08:00:00.0000000",
"TimeZone": "UTC"
},
"StartDateTime": {
"DateTime": "2017-12-18T08:00:00.0000000",
"TimeZone": "UTC"
}
}
}
Sample request
The following sample requests marks a previously flagged mail message as complete
PATCH https://outlook.office.com/api/beta/me/messages/AAMkADk0MGFkODE3LWE4MmYtNDRhOS04OGQxLTM4NzJkSLkRkXbBznTvAAEwgCZNAAA=
Content-Type: application/json; charset=utf-8
Content-Length: 164
{
"Flag": {
"CompletedDateTime":{
"DateTime": "2018-02-05T18:00:00",
"TimeZone": "Pacific Standard Time"
},
"FlagStatus": "Complete"
}
}
Sample response
HTTP/1.1 200 OK
{
"Id": "AAMkADk0MGFkODE3LWE4MmYtNDRhOS04OGQxLTM4NzJkSLkRkXbBznTvAAEwgCZNAAA=",
"CreatedDateTime": "2017-12-15T22:11:41Z",
"LastModifiedDateTime": "2017-12-16T00:49:44Z",
"ChangeKey": "CQAAABYAAABmngqUDhbeSLkRkXbBznTvAAEw/ThM",
"Categories": [],
"ReceivedDateTime": "2017-12-15T22:11:41Z",
"SentDateTime": "2017-12-15T22:11:36Z",
"HasAttachments": false,
"InternetMessageId": "<e711230d-d066-469e-a128-c429c5789d97@SINGMEHUB02.gme.gbl>",
"Subject": "An agent sent you a message in Microsoft Teams",
"BodyPreview": "Hi John,\r\nYou're missing all the action in Microsoft Teams\r\n\r\n\r\nAn agent\r\nSent a new message to your chat\r\n\r\n Open Microsoft Teams\r\n\r\nRather not receive these emails? Click your profile picture, select Options and then Notificatio",
"Importance": "Normal",
"ParentFolderId": "AAMkADk0MGFkODE3LWE4MmYtNDRhOS04OGQxLTM4NzJkNzQ0NWVlMgAuAAAAAAB79HWXBjsTRocnYZpOfEpCAQCHGmLqkYhISaO_lSymODLQABa6L5YsAAA=",
"ConversationId": "AAQkADk0MGFkODE3LWE4MmYtNDRhOS04OGQxLTM4NzJkNzQ0NWVlMgAQAPQcMVQTnE5Aql13YD1jbQw=",
"ConversationIndex": "AQHTdfGv9BwxVBOcTkCqXXdgPWNtDA==",
"IsDeliveryReceiptRequested": null,
"IsReadReceiptRequested": false,
"IsRead": true,
"IsDraft": false,
"WebLink": "https://outlook.office365.com/owa/?ItemID=AAMkADTvAAEwgCZNAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
"InferenceClassification": "Other",
"UnsubscribeData": [],
"UnsubscribeEnabled": false,
"Body": {
"ContentType": "HTML",
"Content": "<html style=\"font-family:'Segoe UI',Tahoma,Geneva,Verdana,sans-serif; font-size:18px\"></html>\r\n"
},
"Sender": {
"EmailAddress": {
"Name": "Microsoft Teams",
"Address": "noreply@email.teams.microsoft.com"
}
},
"From": {
"EmailAddress": {
"Name": "Microsoft Teams",
"Address": "noreply@email.teams.microsoft.com"
}
},
"ToRecipients": [
{
"EmailAddress": {
"Name": "John",
"Address": "john@contoso.com"
}
}
],
"CcRecipients": [],
"BccRecipients": [],
"ReplyTo": [],
"MentionsPreview": null,
"Flag": {
"FlagStatus": "Complete",
"CompletedDateTime": {
"DateTime": "2018-02-06T00:00:00.0000000",
"TimeZone": "UTC"
}
}
}
Response type
The updated message.
Delete messages
Note
Be careful when you delete messages. Deleted contents might not be recoverable. To learn more, see Deleting items.
Delete a message
Minimum required scope
One of the following:
DELETE https://outlook.office.com/api/beta/me/messages/{message_id}
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | string | The ID of the message to delete. |
Sample request
DELETE https://outlook.office.com/api/beta/me/messages/AAMkAGE0Mz8TBAAA=
Sample response
Status code: 204
Move or copy messages
You can move or copy a message to a folder.
Move a message
Minimum required scope
One of the following:
Move a message to a folder. This creates a new copy of the message in the destination folder.
POST https://outlook.office.com/api/beta/me/messages/{message_id}/move
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | string | The ID of the message to move. |
| Body parameters | ||
| DestinationId | string | The destination folder ID, or the Inbox, Drafts, SentItems, or DeletedItems well-known folder name. |
Sample request
POST https://outlook.office.com/api/beta/me/messages/AAMkAGI2TIy-AAA=/move
Content-Type: application/json
{
"DestinationId": "AAMkAGI2AAEJAAA="
}
Sample response
Status code: 201
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGE0MGz_vSAAA=')",
"@odata.etag": "W/\"CQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTJqP\"",
"Id": "AAMkAGI2shBhAAA=",
"ChangeKey": "CQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTJqP",
"InternetMessageId": "SN2PR00M@SN2.namprd00.prod.outlook.com",
"Categories": [],
"CreatedDateTime": "2014-10-20T00:13:21Z",
"LastModifiedDateTime": "2014-10-20T00:13:23Z",
"Subject": "Contract Signing",
"BodyPreview": "There will be a detailed legal review of Project Falcon once the contract is ready.",
"Body": {
"ContentType": "Text",
"Content": "There will be a detailed legal review of Project Falcon once the contract is ready."
},
"Importance": "Normal",
"HasAttachments": false,
"ParentFolderId": "AAMkAGI2AAEJAAA=",
"From": {
"EmailAddress": {
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Alex D"
}
},
"Sender": {
"EmailAddress": {
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Alex D"
}
},
"ToRecipients": [
{
"EmailAddress": {
"Address": "katiej@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Katie Jordan"
}
},
{
"EmailAddress": {
"Address": "garthf@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Garth Fort"
}
}
],
"CcRecipients": [],
"BccRecipients": [],
"ReplyTo": [],
"ConversationId": "AAQkAGI2NGWgitxag=",
"ConversationIndex": "AQHRh6etrkAcds2kw==",
"ReceivedDateTime": "2014-10-20T00:13:21Z",
"SentDateTime": "2014-10-20T00:13:21Z",
"IsDeliveryReceiptRequested": false,
"IsReadReceiptRequested": false,
"IsDraft": false,
"IsRead": true
}
Response type
The message that was moved.
Copy a message
Minimum required scope
One of the following:
Copy a message to a folder.
POST https://outlook.office.com/api/beta/me/messages/{message_id}/copy
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | string | The ID of the message to copy. |
| Body parameters | ||
| DestinationId | string | The destination folder ID, or the Inbox, Drafts, SentItems, or DeletedItems well-known folder name. |
Sample request
POST https://outlook.office.com/api/beta/me/messages/AAMkAGI2TIy-AAA=/copy
Content-Type: application/json
{
"DestinationId": "inbox"
}
Sample response
Status code: 201
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGE0Mz8TDAAA=')",
"@odata.etag": "W/\"CQAAABYAAAAmP1Ln1wcHRariNdTMGAO9AAAS0AIS\"",
"Id": "AAMkAGI2T8DtAAA=",
"ChangeKey": "CQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTJqP",
"InternetMessageId": "SN2PR00M@SN2.namprd00.prod.outlook.com",
"Categories": [],
"CreatedDateTime": "2014-10-20T00:13:21Z",
"LastModifiedDateTime": "2014-10-20T00:13:23Z",
"Subject": "Contract Signing",
"BodyPreview": "There will be a detailed legal review of Project Falcon once the contract is ready.",
"Body": {
"ContentType": "Text",
"Content": "There will be a detailed legal review of Project Falcon once the contract is ready."
},
"Importance": "Normal",
"HasAttachments": false,
"ParentFolderId": "AAMkAGE0MAAEMAAA=",
"From": {
"EmailAddress": {
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Alex D"
}
},
"Sender": {
"EmailAddress": {
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Alex D"
}
},
"ToRecipients": [
{
"EmailAddress": {
"Address": "katiej@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Katie Jordan"
}
},
{
"EmailAddress": {
"Address": "garthf@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Garth Fort"
}
}
],
"CcRecipients": [],
"BccRecipients": [],
"ReplyTo": [],
"ConversationId": "AAQkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAQAKjRc0YJSUBJpofjWgitxag=",
"ConversationIndex": "AQHRh6sdrkAcds2kw==",
"ReceivedDateTime": "2014-10-20T00:13:21Z",
"SentDateTime": "2014-10-20T00:13:21Z",
"IsDeliveryReceiptRequested": false,
"IsReadReceiptRequested": false,
"IsDraft": false,
"IsRead": true
}
Response type
The new copy of the message.
Manage Focused Inbox
Focused Inbox allows you to view important messages in the Focused tab of the Inbox, and the rest of the Inbox messages in the Other tab. The classification system initially organizes Inbox messages in a default way. You can correct and train the system over time through the user interface or programmatically. The more you use it,
the better the system can infer which incoming message as important.
At the programmatic level, the Focused Inbox REST API works on the specified user's messages, and supports an InferenceClassification property for each message. The possible values are Focused and Other, which indicate whether the user considers that message as, respectively, more important and less important. To correct and train the message classification system, use the PATCH operation on the InferenceClassification property at the message level.
The Focused Inbox REST API also lets you create overrides. Each override, represented by an InferenceClassificationOverride instance, is an instruction for the classification system to always designate messages from a specific sender in a consistent way (i.e., always as "Focused" or always as "Other"), regardless of any previously learned approach. You can create, get, update and delete overrides for the specified user. That user's overrides, if any, are accessible in an InferenceClassification navigation property, which is a collection of InferenceClassificationOverride instances. Overrides allow a user more control over the classification of incoming messages, and build greater trust of the classification system.
Note that the classification system learns and applies classification only on incoming messages in the Inbox. Messages in other folders are by default "Focused". Setting up an override affects future messages arriving in the Inbox; the override doesn't modify the InferenceClassification property in existing messages in any folder including the Inbox.
Training the message classification system
Using overrides to classify consistently per sender
- Create an override for a sender
- Get all user overrides
- Update an override for a sender
- Delete a sender override
Update message classification
Minimum required scope
One of the following:
Change the InferenceClassification property of the specified message. If the message is in the Inbox, the user will see that message under the corresponding Focused or Other tab. This kind of correction also trains the message classification system to customize future classification for the specified user.
PATCH https://outlook.office.com/api/beta/me/messages('{message_id}')
PATCH https://outlook.office.com/api/beta/Users('{user_id}')/messages('{message_id}')
| Parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | string | The ID of the draft message to send. |
| user_id | string | The user's email address. |
Response type
The updated message.
Sample request
This example changes the InferenceClassification property to Other for the specified message of the signed-in user's.
PATCH https://outlook.office.com/api/beta/me/messages('AAMkADA1MTQBAAA=')
{
"InferenceClassification": "Other"
}
Sample response
The response object shown here shows the updated InferenceClassification property and is truncated for brevity. An actual PATCH request returns all the properties of the message.
Status code: 200 OK
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('86b6ceaf-57f7-4278-97c4-4da0a97f6cdb@70559e59-b378-49ea-8e53-07a3a3d27f5b')/Messages('AAMkADA1MTQBAAA=')",
"@odata.etag": "W/\"CQAAABYAAADX8oL1Wa7jQbcPAHouCzswAAAffAsD\"",
"Id": "AAMkADA1MTQBAAA=",
"Importance": "Normal",
"Sender": {
"EmailAddress": {
"Name": "Fanny Downs",
"Address": "fannyd@adatum.onmicrosoft.com"
}
},
"From": {
"EmailAddress": {
"Name": "Fanny Downs",
"Address": "fannyd@adatum.onmicrosoft.com"
}
},
"ToRecipients": [
{
"EmailAddress": {
"Name": "Admin",
"Address": "admin@adatum.onmicrosoft.com"
}
}
],
"InferenceClassification": "Other"
}
Create an override for a sender
Minimum required scope
One of the following:
Create an override for a sender identified by an SMTP address. Future messages from that SMTP address will be consistently classified as specified in the override.
Note
- If an override already exists with the same STMP address, then the ClassifyAs and Name fields of that override are updated with the provided values.
- The maximum number of overrides supported for a mailbox is 1000, based on unique sender SMTP addresses.
- The POST operation supports creating only one override at a time. To create multiple overrides, you can send multiple POST requests or batch them.
POST https://outlook.office.com/api/beta/me/InferenceClassification/Overrides
POST https://outlook.office.com/api/beta/Users('{user_id}')/InferenceClassification/Overrides
| Parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| user_id | string | The user's email address. |
Response type
The newly created InferenceClassificationOverride, or updated InferenceClassificationOverride instance if one with the same SMTP address already exists.
Sample request
POST https://outlook.office.com/api/beta/me/InferenceClassification/Overrides
{
"ClassifyAs": "Focused",
"SenderEmailAddress": {
"Name": "Fanny Downs",
"Address": "fannyd@adatum.onmicrosoft.com"
}
}
Sample response
Status code: 201 Created
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/InferenceClassification/Overrides/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('86b6ceaf-57f7-4278-97c4-4da0a97f6cdb@70559e59-b378-49ea-8e53-07a3a3d27f5b')/InferenceClassificationOverrides('98f5bdef-576a-404d-a2ea-07a3cf11a9b9')",
"Id": "98f5bdef-576a-404d-a2ea-07a3cf11a9b9",
"ClassifyAs": "Focused",
"SenderEmailAddress": {
"Name": "Fanny Downs",
"Address": "fannyd@adatum.onmicrosoft.com"
}
}
Get all user overrides
Minimum required scope
One of the following:
Get 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 sender. Initially, a user does not have any overrides.
GET https://outlook.office.com/api/beta/me/InferenceClassification/Overrides
GET https://outlook.office.com/api/beta/Users('{user_id}')/InferenceClassification/Overrides
| Parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| user_id | string | The user's email address. |
Response type
A collection of InferenceClassificationOverride instances. An empty collection is returned if the user doesn't have any overrides set up.
Sample request
GET https://outlook.office.com/api/beta/me/InferenceClassification/Overrides
Sample response
Status code: 200 OK
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/InferenceClassification/Overrides",
"value": [
{
"@odata.id": "https://outlook.office.com/api/beta/Users('86b6ceaf-57f7-4278-97c4-4da0a97f6cdb@70559e59-b378-49ea-8e53-07a3a3d27f5b')/InferenceClassificationOverrides('98f5bdef-576a-404d-a2ea-07a3cf11a9b9')",
"Id": "98f5bdef-576a-404d-a2ea-07a3cf11a9b9",
"ClassifyAs": "Focused",
"SenderEmailAddress": {
"Name": "Fanny Downs",
"Address": "fannyd@adatum.onmicrosoft.com"
}
},
{
"@odata.id": "https://outlook.office.com/api/beta/Users('86b6ceaf-57f7-4278-97c4-4da0a97f6cdb@70559e59-b378-49ea-8e53-07a3a3d27f5b')/InferenceClassificationOverrides('98f5bdef-576a-404d-a2ea-07a3cf34af4r')",
"Id": "98f5bdef-576a-404d-a2ea-07a3cf34af4r",
"ClassifyAs": "Other",
"SenderEmailAddress": {
"Name": "Randi Welch",
"Address": "randiw@adatum.onmicrosoft.com"
}
}
]
}
Update an override for a sender
Minimum required scope
One of the following:
Change the ClassifyAs field of an override as specified.
You cannot use PATCH to change any other fields in an InferenceClassificationOverride instance.
If an override exists for a sender and the sender changes his/her display name, you can use POST to force an update to the Name field in the existing override.
If an override exists for a sender and the sender changes his/her SMTP address, deleting the existing override and creating a new one with the new SMTP address is the only way to "update" the override for this sender.
PATCH https://outlook.office.com/api/beta/me/InferenceClassification/Overrides('{override_id}')
PATCH https://outlook.office.com/api/beta/Users('{user_id}')/InferenceClassification/Overrides('{override_id}')
| Parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| override_id | string | The ID of the override to update. |
| user_id | string | The user's email address. |
Response type
The updated InferenceClassificationOverride instance.
Sample request
The following example changes an override for the signed-in user. The override is for the sender with the SMTP address randiw@adatum.onmicrosoft.com, changed from Other to Focused.
PATCH https://outlook.office.com/api/beta/me/InferenceClassification/Overrides('98f5bdef-576a-404d-a2ea-07a3cf34af4r')
{
"ClassifyAs": "Focused"
}
Sample response
Status code: 200 OK
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/InferenceClassification/Overrides/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('86b6ceaf-57f7-4278-97c4-4da0a97f6cdb@70559e59-b378-49ea-8e53-07a3a3d27f5b')/InferenceClassificationOverrides('98f5bdef-576a-404d-a2ea-07a3cf34af4r')",
"Id": "98f5bdef-576a-404d-a2ea-07a3cf34af4r",
"ClassifyAs": "Focused",
"SenderEmailAddress": {
"Name": "Randi Welch",
"Address": "randiw@adatum.onmicrosoft.com"
}
}
Delete a sender override
Minimum required scope
One of the following:
Delete an override specified by its ID.
DELETE https://outlook.office.com/api/beta/me/InferenceClassification/Overrides('{override_id}')
DELETE https://outlook.office.com/api/beta/Users('{user_id}')/InferenceClassification/Overrides('{override_id}')
| Parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| override_id | string | The ID of the draft message to send. |
| user_id | string | The user's email address. |
Sample request
DELETE https://outlook.office.com/api/beta/me/InferenceClassification/Overrides('98f5bdef-576a-404d-a2ea-07a3cf34af4r')
Sample response
Status code: 204 No Content
Manage @-Mentions (preview)
Calling out a recipient to get the recipient's attention in a message is a common social gesture. The Mention resource provides a light-weight mechanism to notify another recipient, or to get a notification from a sender in a message.
Through the user interface, an app can let a user insert a mention in a message by preceding the mention with @ (commonly used for similar scenarios in other apps, hence the term @-mention). Programmatically, the app can create the mention by adding it to the Mentions property in the same POST call to create the message.
The app can let users look up whether they have been notified in any messages in their Inbox. Users can find details of each mention in a message. They can also delete a mention in a message.
Create mentions in a new message
Get information about mentions in a message
Delete a mention in a message
Create and send mentions as part of a new message
Minimum required scope
One of the following:
Create and send a message supplied in the request body which includes a collection of one or more Mention instances.
This uses the same SendMail action available on the Message resource; in addition, you include the Mentions property as part of the Message body parameter.
POST https://outlook.office.com/api/beta/me/sendmail
| Required parameter | Type | Description |
|---|---|---|
| Body parameters | ||
| Message | Message | The message to send. |
| SavetoSentItems | boolean | Indicates whether to save the message in Sent Items. Default is true. Required only if false. |
Specify the Message parameter with the required ToRecipients property, the Mentions property, and any writable message properties in the request body.
And, for each mention in the Mentions property, you must specify the Mentioned and CreatedBy properties.
Sample request
POST https://outlook.office.com/api/beta/me/sendmail
Content-Type: application/json
{
"Message": {
"Subject": "Project kickoff",
"ToRecipients":[
{
"EmailAddress":{
"Name":"Fanny Downs",
"Address":"fannyd@contoso.onmicrosoft.com"
}
}
],
"Mentions":[
{
"Mentioned":{
"Name":"Dana Swope",
"Address":"danas@contoso.onmicrosoft.com"
},
"CreatedBy": {
"Name":"Randi Welch",
"Address":"randiw@contoso.onmicrosoft.com"
}
}
]
}
}
Sample response
Status code: 202 Accepted
Create mentions as part of a message draft
Minimum required scope
One of the following:
Create a draft of a new message which includes a collection of one or more Mention instances. You can create the draft in any folder and optionally update it before sending.
This uses the same POST method available on the Message resource; in addition, you include its Mentions property in the request body.
POST https://outlook.office.com/api/beta/me/messages
POST https://outlook.office.com/api/beta/me/MailFolders/{folder_id}/messages
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| folder_id | string | The destination folder ID, or the Inbox or Drafts well-known folder name. |
Specify the Mentions property and any writable message properties in the request body.
And, for each mention in the Mentions property, you must specify the Mentioned and CreatedBy properties.
Response type
The draft message.
Sample request
POST https://outlook.office.com/api/beta/me/messages
Content-Type: application/json
{
"Subject": "Party planning",
"ToRecipients":[
{
"EmailAddress":{
"Name":"Fanny Downs",
"Address":"fannyd@contoso.onmicrosoft.com"
}
}
],
"Mentions":[
{
"Mentioned":{
"Name":"Dana Swope",
"Address":"danas@contoso.onmicrosoft.com"
},
"CreatedBy": {
"Name":"Randi Welch",
"Address":"randiw@contoso.onmicrosoft.com"
}
}
]
}
Sample response
The following shows the created draft message.
Note
The response object shown here is truncated for brevity. All of the properties will be returned from an actual call.
Status code: 201 Created
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Messages/$entity",
"@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Messages('AQMkADJmMTUAAAW1fsAAAAA==')",
"@odata.etag":"W/\"CQAAABYAAAAPFhK2FclcRbABBJhCde8iAAAAbYj7\"",
"Id":"AQMkADJmMTUAAAW1fsAAAAA==",
"Body":{
"ContentType":"Text",
"Content":""
},
"BodyPreview":"",
"Sender":null,
"From":null,
"ToRecipients":[
{
"EmailAddress":{
"Name":"Fanny Downs",
"Address":"fannyd@contoso.onmicrosoft.com"
}
}
],
"MentionsPreview":{
"IsMentioned":false
},
"Mentions@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Messages('AQMkADJmMTUAAAW1fsAAAAA%3D%3D')/Mentions",
"Mentions":[
{
"@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Messages('AQMkADJmMTUAAAW1fsAAAAA==')/Mentions('4577bba4-b063-4cea-9073-6f7ca815fcec')",
"Id":"4577bba4-b063-4cea-9073-6f7ca815fcec",
"Mentioned":{
"Name":"Dana Swope",
"Address":"danas@contoso.onmicrosoft.com",
"ExternalId":"72137a84-1a8b-4b92-aa06-cca538e8616b"
},
"MentionText":null,
"ClientReference":null,
"CreatedBy":{
"Name":"Randi Welch",
"Address":"randiw@contoso.onmicrosoft.com",
"ExternalId":"266efe5a-0fd7-4edd-877b-b2d1e561f193"
},
"CreatedDateTime":"2016-07-22T02:22:44Z",
"ServerCreatedDateTime":"2016-07-22T02:22:44.201Z",
"DeepLink":null,
"Application":null
}
]
}
Get all messages that mention the signed-in user
Minimum required scope
One of the following:
Get all the messages in the signed-in user's mailbox, or in the specified folder, that contain a Mention of this user.
This uses the same GET method available on the Message resource; in addition, you include a $filter query parameter on the MentionsPreview property.
By default, a GET /me/messages call does not return the Mentions property. Use the $expand query parameter to find details of each mention in a message.
Note
Make sure your actual call encodes the space characters in the query parameter string appropriately.
GET https://outlook.office.com/api/beta/me/messages?$filter=MentionsPreview/IsMentioned eq true
GET https://outlook.office.com/api/beta/me/MailFolders/{folder_id}/messages?$filter=MentionsPreview/IsMentioned eq true
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| folder_id | string | The destination folder ID, or the Inbox or Drafts well-known folder name. |
Response type
The requested message collection.
Sample request
The example below filters all messages in the signed-in user's mailbox for those that mention the user.
It uses $select to return a subset of the properties of each message in the response. It also incorporates
URL encoding for the space characters in the query parameter string.
GET https://outlook.office.com/api/beta/me/messages?$filter=MentionsPreview/IsMentioned%20eq%20true&$select=Subject,Sender,ReceivedDateTime,MentionsPreview
Sample response
The response contains two messages that mention the signed-in user.
Status code: 200 OK
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Messages(Subject,Sender,ReceivedDateTime,MentionsPreview)",
"value":[
{
"@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Messages('AQMkADJmMTUAAAgVZAAAA')",
"@odata.etag":"W/\"CQAAABYAAAAPFhK2FclcRbABBJhCde8iAAAAAATI\"",
"Id":"AQMkADJmMTUAAAgVZAAAA",
"ReceivedDateTime":"2016-07-21T07:40:21Z",
"Subject":"Re: Start planning soon",
"Sender":{
"EmailAddress":{
"Name":"Randi Welch",
"Address":"randiw@contoso.onmicrosoft.com"
}
},
"MentionsPreview":{
"IsMentioned":true
}
},
{
"@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Messages('AQMkADJmMTUAAAjwVAAAA')",
"@odata.etag":"W/\"CQAAABYAAAAPFhK2FclcRbABBJhCde8iAAAAAEGj\"",
"Id":"AQMkADJmMTUAAAjwVAAAA",
"ReceivedDateTime":"2016-07-21T07:40:20Z",
"Subject":"Re: Start planning soon",
"Sender":{
"EmailAddress":{
"Name":"Randi Welch",
"Address":"randiw@contoso.onmicrosoft.com"
}
},
"MentionsPreview":{
"IsMentioned":true
}
}
]
}
Get details of each mention in a message
Minimum required scope
One of the following:
Get a message with the details of each Mention in the message expanded.
This uses the same GET method available on the Message resource; in addition, you include a $expand query parameter on the Mentions navigation property.
GET https://outlook.office.com/api/beta/me/messages('{message_id}')?$expand=Mentions
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | string | The ID of the requested message. |
Response type
The requested message.
Sample request
In the following example, the signed-in user is Dana Swope. The example shows getting the details of all the mentions in the specified message in Dana's mailbox.
GET https://outlook.office.com/api/beta/me/messages('AQMkADJmMTUAAAgVZAAAA')?$expand=Mentions
Sample response
The following shows the requested message including details of each mention in the Mentions property. This message includes 2 mentions, one for the signed-in user Dana, and the other for Randi Welch.
Note
The response object shown here is truncated for brevity to focus on the properties related to supporting Mention.
Status code: 200 OK
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Messages/$entity",
"@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Messages('AQMkADJmMTUAAAgVZAAAA')",
"@odata.etag":"W/\"CQAAABYAAAAPFhK2FclcRbABBJhCde8iAAAAAATI\"",
"Id":"AQMkADJmMTUAAAgVZAAAA",
"Subject":"Start planning soon",
"Body":{
"ContentType":"HTML",
"Content":"<html><head></head><body"><p><a href=\"mailto:danas@contoso.onmicrosoft.com\">@Dana Swope</a>,<a href=\"mailto:randiw@contoso.onmicrosoft.com\">@Randi Welch</a>, forgot to mention, I will be away this weekend. I can start on Monday though.</p></body></html>"
},
"BodyPreview":"@Dana Swope<mailto:danas@contoso.onmicrosoft.com>, @Randi Welch, forgot to mention, I will be away this weekend. I can start on Monday though.",
"Sender":{
"EmailAddress":{
"Name":"Fanny Downs",
"Address":"fannyd@contoso.onmicrosoft.com"
}
},
"From":{
"EmailAddress":{
"Name":"Fanny Downs",
"Address":"fannyd@contoso.onmicrosoft.com"
}
},
"ToRecipients":[
{
"EmailAddress":{
"Name":"Dana Swope",
"Address":"danas@contoso.onmicrosoft.com"
}
},
{
"EmailAddress":{
"Name":"Randi Welch",
"Address":"randiw@contoso.onmicrosoft.com"
}
}
],
"CcRecipients":[
],
"BccRecipients":[
],
"MentionsPreview":{
"IsMentioned":true
},
"Mentions@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Messages('AQMkADJmMTUAAAgVZAAAA')/Mentions",
"Mentions":[
{
"@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Messages('AQMkADJmMTUAAAgVZAAAA')/Mentions('138f4c0a-1130-4776-b780-bf79d73abb3f')",
"Id":"138f4c0a-1130-4776-b780-bf79d73abb3f",
"Mentioned":{
"Name":"Dana Swope",
"Address":"danas@contoso.onmicrosoft.com",
"ExternalId":"72137a84-1a8b-4b92-aa06-cca538e8616b"
},
"MentionText":null,
"ClientReference":null,
"CreatedBy":{
"Name":"Fanny Downs",
"Address":"fannyd@contoso.onmicrosoft.com",
"ExternalId":"266efe5a-0fd7-4edd-877b-b2d1e561f193"
},
"CreatedDateTime":"2016-07-21T07:40:20.152Z",
"ServerCreatedDateTime":"2016-07-21T07:40:20.152Z",
"DeepLink":null,
"Application":null
},
{
"@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Messages('AQMkADJmMTUAAAgVZAAAA')/Mentions('7b94df1a-0086-482a-b0da-e62fae12f983')",
"Id":"7b94df1a-0086-482a-b0da-e62fae12f983",
"Mentioned":{
"Name":"Randi Welch",
"Address":"randiw@contoso.onmicrosoft.com",
"ExternalId":"266efe5a-0fd7-4edd-877b-b2d1e561f193"
},
"MentionText":null,
"ClientReference":null,
"CreatedBy":{
"Name":"Fanny Downs",
"Address":"fannyd@contoso.onmicrosoft.com",
"ExternalId":"266efe5a-0fd7-4edd-877b-b2d1e561f193"
},
"CreatedDateTime":"2016-07-21T07:40:20.158Z",
"ServerCreatedDateTime":"2016-07-21T07:40:20.158Z",
"DeepLink":null,
"Application":null
}
]
}
Delete a mention
Minimum required scope
One of the following:
Deletes the specified mention in the specified message in the signed-in user's mailbox.
DELETE https://outlook.office.com/api/beta/me/messages('{message_id}')/mentions('{mention_id}')
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| mention_id | string | The ID of the mention to delete. |
| message_id | string | The ID of the message which contains the mention. |
Sample request
DELETE https://outlook.office.com/api/beta/me/messages('AAMkADA1MTk1ZAAAKXBQCAAA=')/mentions('7b94df1a-0086-482a-b0da-e62fae12f983')
Sample response
Status code: 204 No Content
Manage rules (preview)
In Outlook, you can set up rules for incoming messages in the Inbox to carry out specific actions if certain conditions are met.
Programmatically, you can access rules through the MessageRules navigation property of the Inbox folder. Each rule is represented by the MessageRule resource, available rule actions are represented by the MessageRuleActions complex type, and available rule conditions and exceptions are represented by the MessageRulePredicates complex type.
Create rules (preview)
Minimum required scope
Create a rule by specifying a set of conditions and actions. Outlook carries out those actions if an incoming message in the user's Inbox meets the specified conditions.
POST https://outlook.office.com/api/beta/me/mailfolders/inbox/messagerules
The following are body parameters that are typically used when creating rules; you can specify any other writable MessageRule properties as appropriate in the request body.
| Body parameters | Type | Description |
|---|---|---|
| Actions | MessageRuleActions | Actions to be taken on a message when the corresponding conditions, if any, are fulfilled. Required. |
| Conditions | MessageRulePredicates | Conditions that when fulfilled, will trigger the corresponding actions for that rule. Optional. |
| DisplayName | String | The display name of the rule. Required. |
| Exceptions | MessageRulePredicates | Represents exception conditions for the rule. Optional. |
| IsEnabled | Boolean | Indicates whether the rule is enabled to be applied to messages. Optional. |
| Sequence | Int32 | Indicates the order in which the rule is executed, among other rules. Required. |
Sample request
The following rule forwards an incoming message to Alex Wilbur if the sender's name includes the term "adele".
POST https://outlook.office.com/api/beta/me/mailfolders/inbox/messagerules
Content-Type: application/json
{
"DisplayName": "From partner",
"Sequence": 2,
"IsEnabled": true,
"Conditions": {
"SenderContains": [
"adele"
]
},
"Actions": {
"ForwardTo": [
{
"EmailAddress": {
"Name": "Alex Wilbur",
"Address": "AlexW@MOD154847.onmicrosoft.com"
}
}
],
"StopProcessingRules": true
}
}
Sample response
Status code: 201 Created
{
"Id":"AQAAAJ5dZqA=",
"DisplayName":"From partner",
"Sequence":2,
"IsEnabled":true,
"HasError":false,
"IsReadOnly":false,
"Conditions":{
"SenderContains":[
"ADELE"
]
},
"Actions":{
"StopProcessingRules":true,
"ForwardTo":[
{
"EmailAddress":{
"Name":"Alex Wilbur",
"Address":"AlexW@MOD154847.onmicrosoft.com"
}
}
]
}
}
Get rules (preview)
Minimum required scope
You can get all the rules defined for the user's Inbox, or get a specific rule by specifying its ID.
Get all the rules for an Inbox
GET https://outlook.office.com/api/beta/me/mailfolders/inbox/messagerules
Sample request
GET https://outlook.office.com/api/beta/me/mailfolders/inbox/messagerules
Sample response
Status code: 200 OK
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/MailFolders('inbox')/MessageRules",
"value":[
{
"@odata.id":"https://outlook.office.com/api/beta/Users('94447c6e-ea4c-494c-a9ed-d905e366c5cb@007e925e-fb5a-4f60-9cb6-58a21e692480')/MailFolders('inbox')/MessageRules('AQAAAJ5dZp8=')",
"Id":"AQAAAJ5dZp8=",
"DisplayName":"Remove spam",
"Sequence":1,
"IsEnabled":true,
"HasError":false,
"IsReadOnly":false,
"Conditions":{
"SubjectContains":[
"enter to win"
]
},
"Actions":{
"Delete":true,
"StopProcessingRules":true
}
},
{
"@odata.id":"https://outlook.office.com/api/beta/Users('94447c6e-ea4c-494c-a9ed-d905e366c5cb@007e925e-fb5a-4f60-9cb6-58a21e692480')/MailFolders('inbox')/MessageRules('AQAAAJ5dZqA=')",
"Id":"AQAAAJ5dZqA=",
"DisplayName":"From partner",
"Sequence":2,
"IsEnabled":true,
"HasError":false,
"IsReadOnly":false,
"Conditions":{
"SenderContains":[
"ADELE"
]
},
"Actions":{
"StopProcessingRules":true,
"ForwardTo":[
{
"EmailAddress":{
"Name":"Alex Wilbur",
"Address":"AlexW@MOD154847.onmicrosoft.com"
}
}
]
}
}
]
}
Get a specific rule
GET https://outlook.office.com/api/beta/me/mailfolders/inbox/messagerules('{rule_id}')
| URL parameters | Type | Description |
|---|---|---|
| rule_id | String | The ID of the rule to get. |
Sample request
GET https://outlook.office.com/api/beta/me/mailfolders/inbox/messagerules('AQAAAJ5dZqA=')
Sample response
Status code: 200 OK
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/MailFolders('inbox')/MessageRules/$entity",
"@odata.id":"https://outlook.office.com/api/beta/Users('94447c6e-ea4c-494c-a9ed-d905e366c5cb@007e925e-fb5a-4f60-9cb6-58a21e692480')/MailFolders('inbox')/MessageRules('AQAAAJ5dZqA=')",
"Id":"AQAAAJ5dZqA=",
"DisplayName":"From partner",
"Sequence":2,
"IsEnabled":true,
"HasError":false,
"IsReadOnly":false,
"Conditions":{
"SenderContains":[
"ADELE"
]
},
"Actions":{
"StopProcessingRules":true,
"ForwardTo":[
{
"EmailAddress":{
"Name":"Alex Wilbur",
"Address":"AlexW@MOD154847.onmicrosoft.com"
}
}
]
}
}
Update rules (preview)
Minimum required scope
Change writable properties on a rule and save the changes.
PATCH https://outlook.office.com/api/beta/me/mailfolders/inbox/messagerules('{rule_id}')
| URL parameters | Type | Description |
|---|---|---|
| rule_id | String | The ID of the rule to update. |
Sample request
The following example changes the name of the rule, and the actions to be taken for that rule in the last example, from forwarding to an address to marking its importance as high.
PATCH https://outlook.office.com/api/beta/me/mailfolders/inbox/messagerules('AQAAAJ5dZqA=')
Content-Type: application/json
{
"DisplayName": "Important from partner",
"Actions": {
"MarkImportance": "High"
}
}
Sample response
Status code: 200 OK
{
"Id":"AQAAAJ5dZqA=",
"DisplayName":"Important from partner",
"Sequence":2,
"IsEnabled":true,
"HasError":false,
"IsReadOnly":false,
"Conditions":{
"SenderContains":[
"ADELE"
]
},
"Actions":{
"MarkImportance": "High"
}
}
Delete rules (preview)
Minimum required scope
Delete the specified rule.
DELETE https://outlook.office.com/api/beta/me/mailfolders/inbox/messagerules('{rule_id}')
| URL parameters | Type | Description |
|---|---|---|
| rule_id | String | The ID of the rule to delete. |
Sample request
DELETE https://outlook.office.com/api/beta/me/mailfolders/inbox/messagerules('AQAAAJ5dZp8=')
Sample response
Status code: 204 No Content
Unsubscribe (preview)
Minimum required scope
One of the following:
Submits a email request on behalf of the signed-in user to unsubscribe from an email distribution list. Uses
the information in the List-Unsubscribe header.
POST https://outlook.office.com/api/beta/me/messages('{message_id}')/unsubscribe
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | string | The ID of the draft message to send. |
Message senders can use mailing lists in a user-friendly way by including the option for recipients to opt out. They can do so by specifying the List-Unsubscribe header in each message following RFC-2369.
Note
In particular, for the Unsubscribe action to work, the sender must specify mailto: and not URL-based unsubscribe information.
Setting that header would also set the UnsubscribeEnabled property of the Message instance to true, and the UnsubscribeData property to the header data.
If the UnsubscribeEnabled property of a message is true, you can use the Unsubscribe action to unsubscribe the user from similar future messages as managed by the message sender.
A successful Unsubscribe action moves the message to the Deleted Items folder. The actual exclusion of the user from future mail distribution is managed by the sender.
Sample request
POST https://outlook.office.com/api/beta/me/messages('AAMkADA1MTk1ZAAAKXBQCAAA=')/unsubscribe
Sample response
Status code: 202 Accepted
Get language choices (preview)
Minimum required scope
One of the following:
Get the list of locales and languages that are supported for the user, as configured on the user's mailbox server.
The user's preferred language is selected from this supported list. You can get the preferred language by getting the user's mailbox settings.
GET https://outlook.office.com/api/beta/me/SupportedLanguages
Response type
Collection of LocaleInfo.
Sample request
GET https://outlook.office.com/api/beta/me/SupportedLanguages
Sample response
The example response below is truncated for brevity to focus on the JSON format of the response.
Status code: 200
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Collection(Microsoft.OutlookServices.LocaleInfo)",
"value":[
{
"Locale":"af-ZA",
"DisplayName":"Afrikaans (Suid-Afrika)"
},
{
"Locale":"en-US",
"DisplayName":"English (United States)"
},
{
"Locale":"en-CA",
"DisplayName":"English (Canada)"
}
]
}
Get time zone choices (preview)
Minimum required scope
One of the following:
Get the list of time zones that are supported for the user, as configured on the user's mailbox server.
You can optionally specify to have time zones returned in the Windows time zone or Internet Assigned Numbers Authority (IANA) time zone (also known as Olson time zone) format. If you don't specify a format, the time zones are retured in the Windows time zone format.
The user's preferred time zone is selected from this supported list. You can get the preferred time zone by getting the user's mailbox settings.
GET https://outlook.office.com/api/beta/me/SupportedTimeZones(TimeZoneStandard='{timezone_format}')
| Optional parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| timezone_format | TimeZoneStandard | A time zone format. Supported values are: Windows and Iana. |
Response type
Collection of TimeZoneInformation.
Sample request
The following example gets the list of supported times zones for the signed-in user in Windows format.
GET https://outlook.office.com/api/beta/me/SupportedTimeZones(TimeZoneStandard='Windows')
Sample response
The example response below is truncated for brevity to focus on the JSON format of the response.
Status code: 200
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Collection(Microsoft.OutlookServices.TimeZoneInformation)",
"value":[
{
"Alias":"Dateline Standard Time",
"DisplayName":"(UTC-12:00) International Date Line West"
},
{
"Alias":"Samoa Standard Time",
"DisplayName":"(UTC+13:00) Samoa"
},
{
"Alias":"UTC-11",
"DisplayName":"(UTC-11:00) Coordinated Universal Time-11"
},
{
"Alias":"Aleutian Standard Time",
"DisplayName":"(UTC-10:00) Aleutian Islands"
}
]
}
Sample request
The following example gets the list of supported times zones in IANA format.
GET https://outlook.office.com/api/beta/me/SupportedTimeZones(TimeZoneStandard='Iana')
Sample response
The example response below is truncated for brevity to focus on the JSON format of the response.
Status code: 200
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Collection(Microsoft.OutlookServices.TimeZoneInformation)",
"value":[
{
"Alias":"Etc/GMT+12",
"DisplayName":"Etc/GMT+12"
},
{
"Alias":"US/Samoa",
"DisplayName":"US/Samoa"
},
{
"Alias":"Etc/GMT+11",
"DisplayName":"Etc/GMT+11"
},
{
"Alias":"US/Aleutian",
"DisplayName":"US/Aleutian"
}
]
}
Get mailbox settings
Minimum required scope
Get the settings for the primary mailbox of the user. Examples of settings include the user's preferred language and default time zone, and any automatic reply settings.
The user's preferred language and time zone are among the choices that the mailbox server has been configured with. You can get the lists of such supported languages and supported time zones for the user.
GET https://outlook.office.com/api/beta/me/MailboxSettings
Response type
To get just the preferred language setting among all mailbox settings:
GET https://outlook.office.com/api/beta/me/MailboxSettings/Language
Response type
To get just the preferred time zone setting among all mailbox settings:
GET https://outlook.office.com/api/beta/me/MailboxSettings/TimeZone
Response type
A string that represents the preferred time zone in Windows time zone format.
You can also get specifically the auto reply settings.
Sample request
The following example gets all the mailbox settings for the signed-in user.
GET https://outlook.office.com/api/beta/me/MailboxSettings
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/MailboxSettings",
"AutomaticRepliesSetting": {
"Status": "Scheduled",
"ExternalAudience": "All",
"ScheduledStartDateTime": {
"DateTime": "2016-03-14T07:00:00.0000000",
"TimeZone": "UTC"
},
"ScheduledEndDateTime": {
"DateTime": "2016-03-28T07:00:00.0000000",
"TimeZone": "UTC"
},
"InternalReplyMessage": "<html>\n<body>\n<p>I'm at our company's worldwide reunion and will respond to your message as soon as I return.<br>\n</p></body>\n</html>\n",
"ExternalReplyMessage": "<html>\n<body>\n<p>I'm at the Contoso worldwide reunion and will respond to your message as soon as I return.<br>\n</p></body>\n</html>\n"
},
"TimeZone": "Pacific Standard Time",
"Language":{
"Locale":"en-US",
"DisplayName":"English (United States)"
}
}
Get auto reply settings
Minimum required scope
Get the automatic reply settings of the signed-in user's mailbox.
Automatic replies allow you to automatically notify people with a message when they send you email. For example, you can notify them when you are not available and cannot respond to them.
Since automatic replies are part of the user's mailbox settings (represented by MailboxSettings), you can view automatic replies settings by getting all mailbox settings, which include automatic replies settings, or by getting specifically the automatic replies settings.
You can use the Prefer: outlook.timezone HTTP header to specify the preferred time zone to display the ScheduledStartDateTime and ScheduledEndDateTime values.
GET https://outlook.office.com/api/beta/me/MailboxSettings/AutomaticRepliesSetting
Response type
Sample request
GET https://outlook.office.com/api/beta/me/MailboxSettings/AutomaticRepliesSetting
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/MailboxSettings/AutomaticRepliesSetting",
"Status": "AlwaysEnabled",
"ExternalAudience": "None",
"ScheduledStartDateTime": {
"DateTime": "2016-03-19T02:00:00.0000000",
"TimeZone": "UTC"
},
"ScheduledEndDateTime": {
"DateTime": "2016-03-20T02:00:00.0000000",
"TimeZone": "UTC"
},
"InternalReplyMessage": "<html>\n<body>\n<p>I'm at our company's worldwide reunion and will respond to your message as soon as I return.<br>\n</p></body>\n</html>\n",
"ExternalReplyMessage": "<html>\n<body>\n<p>I'm at the Contoso worldwide reunion and will respond to your message as soon as I return.<br>\n</p></body>\n</html>\n"
}
Update auto reply settings
Minimum required scope
Automatic replies are part of the user's mailbox settings (represented by MailboxSettings). You can enable, configure, or disable automatic replies by updating the corresponding mailbox settings.
Note
You cannot create or delete any mailbox settings.
PATCH https://outlook.office.com/api/beta/me/MailboxSettings
Response type
Sample request
Following the previous example of getting automatic replies settings, the next example changes
the Status from AlwaysEnabled to Scheduled, and the start and end dates to a different date range.
PATCH https://outlook.office.com/api/beta/me/MailboxSettings
Content-Type: application/json
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/MailboxSettings",
"AutomaticRepliesSetting": {
"Status": "Scheduled",
"ScheduledStartDateTime": {
"DateTime": "2016-03-20T18:00:00.0000000",
"TimeZone": "UTC"
},
"ScheduledEndDateTime": {
"DateTime": "2016-03-28T18:00:00.0000000",
"TimeZone": "UTC"
}
}
}
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/MailboxSettings",
"AutomaticRepliesSetting": {
"Status": "Scheduled",
"ExternalAudience": "None",
"ScheduledStartDateTime": {
"DateTime": "2016-03-20T02:00:00.0000000",
"TimeZone": "UTC"
},
"ScheduledEndDateTime": {
"DateTime": "2016-03-28T02:00:00.0000000",
"TimeZone": "UTC"
},
"InternalReplyMessage": "<html>\n<body>\n<p>I'm at our company's worldwide reunion and will respond to your message as soon as I return.<br>\n</p></body>\n</html>\n",
"ExternalReplyMessage": "<html>\n<body>\n<p>I'm at the Contoso worldwide reunion and will respond to your message as soon as I return.<br>\n</p></body>\n</html>\n"
},
"TimeZone": "Pacific Standard Time",
"Language":{
"Locale":"en-US",
"DisplayName":"English (United States)"
}
}
Get MailTips (preview)
Minimum required scope
One of the following:
Get the MailTips of one or more recipients as available to the signed-in user. Note that this is carried out as a POST operation to the GetMailTips action.
POST https://outlook.office.com/api/beta/me/GetMailTips
| Required parameter | Type | Description |
|---|---|---|
| Body parameters | ||
| EmailAddresses | Collection(String) | A collection of SMTP addresses of recipients to get MailTips for. |
| MailTipsOptions | MailTipsType | The kinds of MailTips to get for the specified recipients. |
Response type
Collection of MailTips.
Sample request
The following example gets MailTips for the specified recipients, for any automatic reply settings and mailbox full status.
POST https://outlook.office.com/api/beta/me/GetMailTips
Content-Type: application/json
{
"EmailAddresses": [
"danas@contoso.onmicrosoft.com",
"fannyd@contoso.onmicrosoft.com"
],
"MailTipsOptions": "AutomaticReplies, MailboxFullStatus"
}
Sample response
Status code: 200 OK
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Collection(Microsoft.OutlookServices.MailTips)",
"value":[
{
"EmailAddress":{
"Name":"",
"Address":"danas@contoso.onmicrosoft.com"
},
"AutomaticReplies":{
"Message":"<style type=\"text/css\" style=\"\">\r\n<!--\r\np\r\n\t{margin-top:0;\r\n\tmargin-bottom:0}\r\n-->\r\n</style>\r\n<div dir=\"ltr\">\r\n<div id=\"x_divtagdefaultwrapper\" style=\"font-size:12pt; color:#000000; background-color:#FFFFFF; font-family:Calibri,Arial,Helvetica,sans-serif\">\r\n<p>Hi, I am on vacation right now. I'll get back to you after I return.<br>\r\n</p>\r\n</div>\r\n</div>",
"MessageLanguage":{
"Locale":"en-US",
"DisplayName":"English (United States)"
}
},
"MailboxFull":false
},
{
"EmailAddress":{
"Name":"",
"Address":"fannyd@contoso.onmicrosoft.com"
},
"AutomaticReplies":{
"Message":""
},
"MailboxFull":false
}
]
}
Get attachments
You can get an attachment collection or get an attachment.
Get an attachment collection
Minimum required scope
One of the following:
Get the attachments from a particular message.
GET https://outlook.office.com/api/beta/me/messages/{message_id}/attachments
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | string | The message ID. |
Note
By default, each attachment in the response includes all its properties corresponding to that attachment type. Use $select to specify only those properties you need for best performance. The Id property is always returned. See OData query parameters for filtering, sorting, and paging parameters.
Response type
An attachment collection which can be of the type FileAttachment, ItemAttachment, or ReferenceAttachment.
Sample requests and responses
The following example shows how to use $select to specify returning only the Name property of each file attachment in the response. Refer to the sample response in Get an attachment for a full list of properties that would be returned for an attachment if you don't use $select.
Sample request
GET https://outlook.office.com/api/beta/me/messages/AAMkAGI2THVSAAA=/attachments?$select=Name
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages('AAMkAGI2THVSAAA%3D')/Attachments(Name)",
"value": [
{
"@odata.type": "#Microsoft.OutlookServices.FileAttachment",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGI2THVSAAA=')/Attachments('AAMkAGI2j4kShdM=')",
"Id": "AAMkAGI2j4kShdM=",
"Name": "minutes.docx"
}
]
}
The following example shows getting the only attachment which is an Outlook mail item. The response includes an attachment ID which is also the ID of the attached message.
GET https://outlook.office.com/api/beta/me/messages('AAMkADFiNTPAAA=')/attachments
Content-Type: application/json
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages('AAMkADFiNTPAAA%3D')/Attachments",
"value": [
{
"@odata.type": "#Microsoft.OutlookServices.ItemAttachment",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-20075df800e5@1717622f-1d94-4d0c-9d74-f907ad6677b4')/Messages('AAMkADFiNTPAAA=')/Attachments('AAMkADFiNTAUhhYuYi0=')",
"Id": "AAMkADFiNTAUhhYuYi0=",
"Name": "How to retrieve item attachment using Outlook REST API",
"ContentType": message/rfc822,
"Size": 71094,
"IsInline": false,
"LastModifiedDateTime": "2015-09-24T05:57:59Z",
}
]
}
Get an attachment
Minimum required scope
One of the following:
Get an attachment from a particular message.
GET https://outlook.office.com/api/beta/me/messages/{message_id}/attachments/{attachment_id}
Note
See OData query parameters for filtering, sorting, and paging parameters.
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | string | The message ID. |
| attachment_id | string | The attachment ID. |
Note
By default, the response includes all the properties of the attachment. Use $select to specify only those properties you need for best performance. Refer to Get an attachment collection for an example. The Id property is always returned. See OData query parameters for filtering, sorting, and paging parameters.
Response type
The requested file attachment, item attachment, or reference attachment.
Sample request (file attachment)
The following example gets the file attached to a specific message.
GET https://outlook.office.com/api/beta/me/messages/AAMkAGI2THVSAAA=/attachments/AAMkAGI2j4kShdM=
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages('AAMkAGI2THVSAAA%3D')/Attachments/$entity",
"@odata.type": "#Microsoft.OutlookServices.FileAttachment",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGI2THVSAAA=')/Attachments('AAMkAGI2j4kShdM=')",
"Id": "AAMkAGI2j4kShdM=",
"LastModifiedDateTime": "2014-10-20T00:41:52Z",
"Name": "minutes.docx",
"ContentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"Size": 11585,
"IsInline": false,
"ContentId": null,
"ContentLocation": null,
"ContentBytes": "UEsDBBQABgAIAAAAIQDCAAA4KQAAAAA="
}
Sample request (reference attachment)
The following example gets the reference attachment of a message.
GET https://outlook.office.com/api/beta/me/messages/AAMkAGE1Mbs88AADUv0uFAAA=/attachments/AAMkAGE1Mbs88AADUv0uFAAABEgAQAPSg72tgf7hJp0PICVGCc0g=
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#users('ddfcd489-628b-40d7-b48b-57002df800e5')/messages('AAMkAGE1Mbs88AADUv0uFAAA%3D')/attachments/$entity",
"@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
"Id": "AAMkAGE1Mbs88AADUv0uFAAABEgAQAPSg72tgf7hJp0PICVGCc0g=",
"LastModifiedDateTime": "2016-03-12T06:04:38Z",
"Name": "Koala picture",
"ContentType": null,
"Size": 382,
"IsInline": false,
"SourceUrl": "https://contoso-my.spoppe.com/personal/danas_contoso_onmicrosoft_com/Documents/Pics/koala.jpg",
"ProviderType": "OneDriveBusiness",
"ThumbnailUrl": null,
"PreviewUrl": null,
"Permission": "Edit",
"IsFolder": false
}
Sample request ($expand on attachments)
The following example gets and expands all 3 reference attachments inline with the message properties.
GET https://outlook.office.com/api/beta/me/messages/AAMkAGE1Mbs88AADUv0uFAAA=/?$expand=attachments
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#users('ddfcd489-628b-40d7-b48b-57002df800e5')/messages/$entity",
"@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AADZsPav\"",
"Id": "AAMkAGE1Mbs88AADUv0uFAAA=",
"CreatedDateTime": "2016-03-08T01:01:57Z",
"LastModifiedDateTime": "2016-03-12T06:18:54Z",
"ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AADZsPav",
"Categories": [ ],
"ReceivedDateTime": "2016-03-08T01:01:57Z",
"SentDateTime": "2016-03-08T01:01:51Z",
"HasAttachments": true,
"InternetMessageId": "<SN2SR0101MB00299F0D7D22EE5D380104ED84B20@SN2SR0101MB0029.namsdf01.sdf.exchangelabs.com>",
"Subject": "RE: New year activity",
"Body": {
"ContentType": "html",
"Content": "<html>\r\n<<body>Let's gather to celebrate the new year! </body>\r\n</html>\r\n"
},
"BodyPreview": "What about the tulips?\r\n________________________________\r\nFrom: Dana Swope <danas@contoso.onmicrosoft.com>\r\nSent: Monday, March 7, 2016 10:51:39 PM\r\nTo: Dana Swope; Culinary Expert Group\r\nSubject: RE: New year activity\r\n\r\nLet's gather to celebrate the new year! ",
"Importance": "Normal",
"ParentFolderId": "AQMkAGE1MQN7j5uzzwAAAIBDAAAAA==",
"Sender": {
"EmailAddress": {
"Name": "Dana Swope",
"Address": "danas@contoso.onmicrosoft.com"
}
},
"From": {
"EmailAddress": {
"Name": "Dana Swope",
"Address": "danas@contoso.onmicrosoft.com"
}
},
"ToRecipients": [
{
"EmailAddress": {
"Name": "Dana Swope",
"Address": "danas@contoso.onmicrosoft.com"
}
},
{
"EmailAddress": {
"Name": "Culinary Expert Group",
"Address": "Chefs@contoso.onmicrosoft.com"
}
}
],
"CcRecipients": [ ],
"BccRecipients": [ ],
"ReplyTo": [ ],
"ConversationId": "AAQkAGE1MMM2SaRFsKgx7BKVfig=",
"ConversationIndex": "AQHRaThgdSG4wzZJpEWwqDHsEpV+KJ9OtWGUgAAkYLI=",
"IsDeliveryReceiptRequested": false,
"IsReadReceiptRequested": false,
"IsRead": true,
"IsDraft": false,
"WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1Mbs88AADUv0uFAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
"InferenceClassification": "Focused",
"UnsubscribeData": [ ],
"UnsubscribeEnabled": false,
"Flag": { "FlagStatus": "NotFlagged" },
"Attachments@odata.context": "https://outlook.office.com/api/beta/$metadata#users('ddfcd489-628b-40d7-b48b-57002df800e5')/messages('AAMkAGE1Mbs88AADUv0uFAAA%3D')/attachments",
"Attachments": [
{
"@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
"Id": "AAMkAGE1Mbs88AADUv0uFAAABEgAQAL53d0u3BKBJmCxKVxZKBZ8=",
"LastModifiedDateTime": "2016-03-12T05:54:31Z",
"Name": "Personal pictures",
"ContentType": null,
"Size": 362,
"IsInline": false,
"SourceUrl": "https://contoso-my.spoppe.com/personal/danas_contoso_onmicrosoft_com/Documents/Pics",
"ProviderType": "OneDriveBusiness",
"ThumbnailUrl": null,
"PreviewUrl": null,
"Permission": "edit",
"IsFolder": true
},
{
"@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
"Id": "AAMkAGE1Mbs88AADUv0uFAAABEgAQAPSg72tgf7hJp0PICVGCc0g=",
"LastModifiedDateTime": "2016-03-12T06:04:38Z",
"Name": "Koala picture",
"ContentType": null,
"Size": 382,
"IsInline": false,
"SourceUrl": "https://contoso-my.spoppe.com/personal/danas_contoso_onmicrosoft_com/Documents/Pics/koala.jpg",
"ProviderType": "OneDriveBusiness",
"ThumbnailUrl": null,
"PreviewUrl": null,
"Permission": "edit",
"IsFolder": false
},
{
"@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
"Id": "AAMkAGE1Mbs88AADUv0uFAAABEgAQAO3wkFiM3KlCpn81m8qS1W0=",
"LastModifiedDateTime": "2016-03-12T06:18:54Z",
"Name": "Hydrangea picture",
"ContentType": null,
"Size": 412,
"IsInline": false,
"SourceUrl": "https://contoso-my.spoppe.com/personal/danas_contoso_onmicrosoft_com/Documents/Pics/hydrangea.jpg",
"ProviderType": "OneDriveBusiness",
"ThumbnailUrl": null,
"PreviewUrl": null,
"Permission": "edit",
"IsFolder": false
}
]
}
Sample request ($expand on nested attachment items)
The following example gets a nested attachment item.
GET https://outlook-sdf.office.com/api/beta/me/messages/AAMkAGE1Mbs88AADUv0uFAAA=/attachments/AAMkAGE1Mbs88AADUv0uFAAABEgAQAL53d0u3BKBJmCxKVxZKBZ8=$expand=Microsoft.OutlookServices.ItemAttachment/Item
Sample response
Status code: 200
{
"Id": "AAMkAGE1Mbs88AADUv0uFAAABEgAQAL53d0u3BKBJmCxKVxZKBZ8=",
"LastModifiedDateTime": "2017-04-25T20:05:55Z",
"Name": "RE: Changes to GetConditionMetadata handler",
"ContentType": null,
"Size": 78927,
"IsInline": false,
"Item": {
"Id": "",
"Name": "How to retrieve item attachment using Outlook REST API",
"ContentType": message/rfc822,
"Size": 71094,
"IsInline": false,
"LastModifiedDateTime": "2015-09-24T05:57:59Z",
}
}
Create attachments
You can create a file attachment or create an item attachment for a message.
Create a file attachment
Minimum required scope
One of the following:
Add a file attachment to a message.
POST https://outlook.office.com/api/beta/me/messages/{message_id}/attachments
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | string | The message ID. |
| Body parameters | ||
| @odata.type | string | #Microsoft.OutlookServices.FileAttachment |
| Name | string | The name of the attachment. |
| ContentBytes | binary | The file to attach. |
Specify the Name and ContentBytes parameters and any writable file attachment properties in the request body.
Response type
The new file attachment.
Create an item attachment
Minimum required scope
One of the following:
Add an item attachment to a message.
POST https://outlook.office.com/api/beta/me/messages/{message_id}/attachments
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | string | The message ID. |
| Body parameters | ||
| @odata.type | string | #Microsoft.OutlookServices.ItemAttachment |
| Name | string | The name of the attachment. |
| Item | A Message or Event entity. | The item to attach. |
Specify the Name and Item parameters and any writable item attachment properties in the request body.
Response type
The new item attachment.
Create a reference attachment
Minimum required scope
One of the following:
Add a reference attachment to a message.
POST https://outlook.office.com/api/beta/me/messages/{message_id}/attachments
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | String | The message ID. |
| Body parameters | ||
| @odata.type | String | #Microsoft.OutlookServices.ReferenceAttachment |
| Name | String | The display name of the attachment. Required. |
| SourceUrl | String | URL to get the attachment content. If this is a URL to a folder, then for the folder to be displayed correctly in Outlook or Outlook on the web, set IsFolder to true. Required. |
Specify the Name and SourceUrl parameters and any writable reference attachment properties in the request body.
Response type
The reference attachment.
Sample request
The following example adds a reference attachment to an existing message. The attachment is a link to a file on OneDrive for Business.
POST https://outlook.office.com/api/beta/me/messages/AAMkAGE1Mbs88AADUv0uFAAA=/attachments
Content-Type: application/json
{
"@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
"Name": "Koala picture",
"SourceUrl": "https://contoso-my.spoppe.com/personal/danas_contoso_onmicrosoft_com/Documents/Pics/koala.jpg",
"ProviderType": "oneDriveBusiness",
"Permission": "Edit",
"IsFolder": "False"
}
Sample response
Status code: 201 Created
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#users('ddfcd489-628b-40d7-b48b-57002df800e5')/messages('AAMkAGE1Mbs88AADUv0uFAAA%3D')/attachments/$entity",
"@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
"Id": "AAMkAGE1Mbs88AADUv0uFAAABEgAQAPSg72tgf7hJp0PICVGCc0g=",
"LastModifiedDateTime": "2016-03-12T06:04:38Z",
"Name": "Koala picture",
"ContentType": null,
"Size": 382,
"IsInline": false,
"SourceUrl": "https://contoso-my.spoppe.com/personal/danas_contoso_onmicrosoft_com/Documents/Pics/koala.jpg",
"ProviderType": "oneDriveBusiness",
"ThumbnailUrl": null,
"PreviewUrl": null,
"Permission": "edit",
"IsFolder": false
}
Sample request
The following example adds a reference attachment in the same call as creating a draft message. The attachment is a link to a file on OneDrive for Business.
POST https://outlook.office.com/api/beta/me/messages
Content-Type: application/json
{
"Subject": "Plan for dinner",
"Body": {
"ContentType": "HTML",
"Content": "Office anniversary is coming soon!"
},
"ToRecipients": [
{
"EmailAddress": {
"Address": "randiw@contoso.onmicrosoft.com"
}
}
],
"Attachments": [
{
"@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
"Name": "Hydrangea picture",
"SourceUrl": "https://contoso-my.spoppe.com/personal/danas_contoso_onmicrosoft_com/Documents/Pics/hydrangea.jpg",
"ProviderType": "oneDriveBusiness",
"Permission": "Edit",
"IsFolder": "False"
}
]
}
Sample response
Status code: 201 Created
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#users('ddfcd489-628b-40d7-b48b-57002df800e5')/messages/$entity",
"@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AADZ8qi1\"",
"Id": "AAMkAGE1Mbs88AADZ0CU9AAA=",
"CreatedDateTime": "2016-03-12T09:04:54Z",
"LastModifiedDateTime": "2016-03-12T09:04:54Z",
"ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AADZ8qi1",
"Categories": [ ],
"ReceivedDateTime": "2016-03-12T09:04:54Z",
"SentDateTime": "2016-03-12T09:04:54Z",
"HasAttachments": true,
"InternetMessageId": "<BL2SR0101MB00188944566BDECE6EDE57F384B60@BL2SR0101MB0018.namsdf01.sdf.exchangelabs.com>",
"Subject": "Plan for dinner",
"Body": {
"ContentType": "html",
"Content": "<html>\r\n<body>\r\nOffice anniversary is coming soon!\r\n</body>\r\n</html>\r\n"
},
"BodyPreview": "Office anniversary is coming soon!",
"Importance": "normal",
"ParentFolderId": "AQMkAGE1MQN7j5uzzwAAAIBDwAAAA==",
"Sender": null,
"From": null,
"ToRecipients": [
{
"EmailAddress": {
"Name": "Randi Welch",
"address": "randiw@contoso.onmicrosoft.com"
}
}
],
"CcRecipients": [ ],
"BccRecipients": [ ],
"ReplyTo": [ ],
"ConversationId": "AAQkAGE1MMAAQAJk0cqqggzpKtIHErqyDkcU=",
"ConversationIndex": "AQHRfD4+mTRyqqCDOkq0gcSurIORxQ==",
"IsDeliveryReceiptRequested": false,
"IsReadReceiptRequested": false,
"IsRead": true,
"IsDraft": true,
"WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1Mbs88AADZ0CU9AAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
"InferenceClassification": "focused",
"UnsubscribeData": [ ],
"UnsubscribeEnabled": false,
"Flag": { "flagStatus": "notFlagged" },
"Attachments@odata.context": "https://outlook.office.com/api/beta/$metadata#users('ddfcd489-628b-40d7-b48b-57002df800e5')/messages('AAMkAGE1Mbs88AADZ0CU9AAA%3D')/attachments",
"Attachments": [
{
"@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
"Id": "AAMkAGE1Mbs88AADZ0CU9AAABEgAQAGe4H1iqXwtLsrCCLLkDxqo=",
"LastModifiedDateTime": null,
"Name": "Hydrangea picture",
"ContentType": null,
"Size": 0,
"IsInline": false,
"SourceUrl": "https://contoso-my.spoppe.com/personal/danas_contoso_onmicrosoft_com/Documents/Pics/hydrangea.jpg",
"ProviderType": "oneDriveBusiness",
"ThumbnailUrl": null,
"PreviewUrl": null,
"Permission": "edit",
"IsFolder": false
}
]
}
Delete attachments
Minimum required scope
One of the following:
Delete the specified attachment of a message. The attachment can be a file attachment, item attachment, or reference attachment.
DELETE https://outlook.office.com/api/beta/me/messages/{message_id}/attachments/{attachment_id}
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| message_id | string | The message ID. |
| attachment_id | string | The attachment ID. |
Sample request
DELETE https://outlook.office.com/api/beta/me/messages/AAMkAGE0Mz8S-AAA=/attachments/AAMkAGE0Mg67gL7o=
Sample response
Status code: 204
Get folders
You can get a folder collection or get a folder in the user's mailbox.
Get a folder collection
Minimum required scope
One of the following:
Get all the mail folders in the signed-in user's mailbox (.../me/MailFolders), or get the folder collection
under the specified folder.
GET https://outlook.office.com/api/beta/me/MailFolders
GET https://outlook.office.com/api/beta/me/MailFolders/{folder_id}/childfolders
Note
See OData query parameters for filtering, sorting, and paging parameters.
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| folder_id | string | The folder ID, or the Inbox, Drafts, SentItems, or DeletedItems well-known folder name, if you're getting folders from a specific folder. |
Sample request
GET https://outlook.office.com/api/beta/me/MailFolders
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/MailFolders",
"value": [
{
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/MailFolders('AAMkAGI2AAEKAAA=')",
"Id": "AAMkAGI2AAEKAAA=",
"DisplayName": "Deleted Items",
"ParentFolderId": "AAMkAGI2AAEIAAA=",
"ChildFolderCount": 0,
"UnreadItemCount": 0,
"TotalItemCount": 1,
"WellKnownName": "deleteditems"
},
{
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/MailFolders('AAMkAGI2AAEPAAA=')",
"Id": "AAMkAGI2AAEPAAA=",
"DisplayName": "Drafts",
"ParentFolderId": "AAMkAGI2AAEIAAA=",
"ChildFolderCount": 0,
"UnreadItemCount": 0,
"TotalItemCount": 0,
"WellKnownName": "drafts"
},
{
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/MailFolders('AAMkAGI2AAEMAAA=')",
"Id": "AAMkAGI2AAEMAAA=",
"DisplayName": "Inbox",
"ParentFolderId": "AAMkAGI2AAEIAAA=",
"ChildFolderCount": 0,
"UnreadItemCount": 6,
"TotalItemCount": 6,
"WellKnownName": "inbox"
},
{
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/MailFolders('AAMkAGI2AAEeAAA=')",
"Id": "AAMkAGI2AAEeAAA=",
"DisplayName": "Junk Email",
"ParentFolderId": "AAMkAGI2AAEIAAA=",
"ChildFolderCount": 0,
"UnreadItemCount": 0,
"TotalItemCount": 0,
"WellKnownName": "junkemail"
},
{
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/MailFolders('AAMkAGI2AAELAAA=')",
"Id": "AAMkAGI2AAELAAA=",
"DisplayName": "Outbox",
"ParentFolderId": "AAMkAGI2AAEIAAA=",
"ChildFolderCount": 0,
"UnreadItemCount": 0,
"TotalItemCount": 0,
"WellKnownName": "outbox"
},
{
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/MailFolders('AAMkAGI2AAEJAAA=')",
"Id": "AAMkAGI2AAEJAAA=",
"DisplayName": "Sent Items",
"ParentFolderId": "AAMkAGI2AAEIAAA=",
"ChildFolderCount": 0,
"UnreadItemCount": 0,
"TotalItemCount": 3,
"WellKnownName": "sentitems"
}
]
}
Response type
The requested folder collection.
Get a folder
Minimum required scope
One of the following:
Get a folder by ID.
Get the signed-in user's folder:
GET https://outlook.office.com/api/beta/me/MailFolders/{folder_id}
Get a mailbox folder shared by a user:
GET https://outlook.office.com/api/beta/users/{user_id}/mailFolders/{folder_id}
Note
See OData query parameters for filtering, sorting, and paging parameters.
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| folder_id | string | The folder ID, or the Inbox, Drafts, SentItems, or DeletedItems well-known folder name. |
Sample request
Get the signed-in user's inbox
GET https://outlook.office.com/api/beta/me/MailFolders/inbox
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/MailFolders/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/MailFolders('AAMkAGI2AAEMAAA=')",
"Id": "AAMkAGI2AAEMAAA=",
"DisplayName": "Inbox",
"ParentFolderId": "AAMkAGI2AAEIAAA=",
"ChildFolderCount": 0,
"UnreadItemCount": 6,
"TotalItemCount": 6,
"WellKnownName": "inbox"
}
Sample request
Get a folder shared by another user
GET https://outlook.office.com/api/beta/users/8c14ebe1-e4ba-4232cd011db47/mailFolders/AAMkADk0MGFkODE3LWE4MmYtNDRhOS04OGQxLTM
Sample response
HTTP/1.1 200 OK
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/MailFolders/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/MailFolders('AAMkADk0MGFkODE3LWE4MmYtNDRhOS04OGQxLTM')",
"Id": "AAMkADk0MGFkODE3LWE4MmYtNDRhOS04OGQxLTM",
"DisplayName": "Inbox",
"ParentFolderId": "AAMkADk0MGFkODE3LWE4MmYtNDRhOS04OGQxLTM4QCHGmLqkYhISaO_lSymODLQABa6L5YpAAA=",
"ChildFolderCount": 4,
"UnreadItemCount": 27962,
"TotalItemCount": 64420
}
Response type
The requested folder.
Synchronize folder hierarchy
You can get a flat table of all folders in a mailbox. When you synchronize a mail folder hierarchy, request this category.
| Endpoint | Folder category |
|---|---|
| Me/MailFolders | Mail folders |
You can only synchronize the top level of each folder category. For example, you can request Me/MailFolders but not Me/MailFolders('inbox').
Synchronization supports both full synchronization that retrieves all of the folders in a hierarchy, and incremental synchronization that retrieves all of the folders that have changed since the last full synchronization.
Minimum required scope
One of the following:
GET https://outlook.office.com/api/beta/me/MailFolders
| Required parameter | Type | Description |
|---|---|---|
| Header parameter | ||
| Prefer | odata.trackchanges | Indicates that the request is a synchronization request. |
| Body parameters | ||
| odata.deltaLink | string | The token that indicates the last time that the folder hierarchy was synchronized. |
If any of the following query parameters - $filter, $orderby, $search, $top - are included in
the request, they are ignored.
Response type
A flat list of the folders in the requested category.
Create folders
Add a new folder to a folder collection.
Create a folder
Minimum required scope
One of the following:
Create a child folder by the name specified in DisplayName. DisplayName is the only writable property for a folder.
POST https://outlook.office.com/api/beta/me/MailFolders/{folder_id}/childfolders
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| folder_id | string | The folder ID, or the Inbox, Drafts, SentItems, or DeletedItems well-known folder name. |
| Body parameters | ||
| DisplayName | string | The display name of the folder. |
Sample request
POST https://outlook.office.com/api/beta/me/MailFolders/inbox/childfolders
Content-Type: application/json
{
"DisplayName": "Company"
}
Sample response
Status code: 201
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/MailFolders('inbox')/ChildFolders/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/MailFolders('AAMkAGE0Mz-l_AAA=')",
"Id": "AAMkAGE0Mz-l_AAA=",
"ParentFolderId": "AAMkAGE0MAAEMAAA=",
"DisplayName": "Company",
"ChildFolderCount": 0,
"UnreadItemCount": 2,
"TotalItemCount": 27,
"WellKnownName": ""
}
Response type
The new folder.
Remarks
You can't create a top-level folder. You can only add a folder to a childfolders endpoint.
Update folders
Change a folder name.
Update a folder
Minimum required scope
One of the following:
Change the folder name to that specified in DisplayName. The name is the only writable property for a folder.
PATCH https://outlook.office.com/api/beta/me/MailFolders/{folder_id}
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| folder_id | string | The folder ID, or the Inbox, Drafts, SentItems, or DeletedItems well-known folder name. |
| Body parameters | ||
| DisplayName | string | The new display name of the folder. |
Sample request
PATCH https://outlook.office.com/api/beta/me/MailFolders/AAMkAGE0Mz-l_AAA=
Content-Type: application/json
{
"DisplayName": "Business"
}
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/MailFolders/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/MailFolders('AAMkAGE0Mz-l_AAA=')",
"Id": "AAMkAGE0Mz-l_AAA=",
"ParentFolderId": "AAMkAGE0MAAEMAAA=",
"DisplayName": "Business",
"ChildFolderCount": 0,
"UnreadItemCount": 4,
"TotalItemCount": 38,
"WellKnownName": ""
}
Response type
The updated folder.
Delete folders
Delete a folder and all of its contents.
Note
Be careful when you delete folders. Deleted contents might not be recoverable. To learn more, see Deleting items.
Delete a folder
Minimum required scope
One of the following:
Delete the folder specified in folder_id.
DELETE https://outlook.office.com/api/beta/me/MailFolders/{folder_id}
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| folder_id | string | The folder ID, or the Inbox, Drafts, SentItems, or DeletedItems well-known folder name. |
Sample request
DELETE https://outlook.office.com/api/BETA/me/MailFolders/AAMkAGE0Mz-l_AAA=
Sample response
Status code: 204
Move or copy folders
You can move or copy a folder to another folder.
Move a folder
Minimum required scope
One of the following:
Move a folder and its contents to another folder by using the Move method.
POST https://outlook.office.com/api/beta/me/MailFolders/{folder_id}/move
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| folder_id | string | The folder ID, or the Inbox, Drafts, SentItems, or DeletedItems well-known folder name. |
| Body parameters | ||
| DestinationId | string | The destination folder ID, or the Inbox, Drafts, SentItems, or DeletedItems well-known folder name. |
Sample request
POST https://outlook.office.com/api/beta/me/MailFolders/AAMkAGE0Mz-l_AAA=/move
Content-Type: application/json
{
"DestinationId": "AAMkAGE0MyxQ9AAA="
}
Sample response
Status code: 201
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/MailFolders/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/MailFolders('AAMkAGE0Mz-l_AAA=')",
"Id": "AAMkAGE0Mz-l_AAA=",
"ParentFolderId": "AAMkAGE0MyxQ9AAA=",
"DisplayName": "Business",
"ChildFolderCount": 0,
"UnreadItemCount": 4,
"TotalItemCount": 38,
"WellKnownName": ""
}
Response type
The folder that was moved.
Copy a folder
Minimum required scope
One of the following:
Copy a folder and its contents to another folder by using the Copy method.
POST https://outlook.office.com/api/beta/me/MailFolders/{folder_id}/copy
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| folder_id | string | The folder ID, or the Inbox, Drafts, SentItems, or DeletedItems well-known folder name. |
| Body parameters | ||
| DestinationId | string | The destination folder ID, or the Inbox, Drafts, SentItems, or DeletedItems well-known folder name. |
Sample request
POST https://outlook.office.com/api/beta/me/MailFolders/AAMkAGE0Mz-l_AAA=/copy
Content-Type: application/json
{
"DestinationId": "inbox"
}
Sample response
Status code: 201
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/MailFolders/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/MailFolders('AAMkAGE0Mz-mAAAA=')",
"Id": "AAMkAGE0Mz-mAAAA=",
"ParentFolderId": "AAMkAGE0MAAEMAAA=",
"DisplayName": "Business",
"ChildFolderCount": 0,
"UnreadItemCount": 4,
"TotalItemCount": 38,
"WellKnownName": ""
}
Response type
The new copy of the folder.
Next steps
Whether you're ready to start building an app or just want to learn more, we've got you covered.
Or, learn more about using the Office 365 platform:
- Outlook REST API on the Outlook Dev Center
- Overview of developing on the Office 365 platform
- Office 365 app authentication and resource authorization
- Manually register your app with Azure AD so it can access Office 365 APIs
- Calendar API reference
- Contacts API reference
- Task REST API (preview)
- OneDrive API
- Discovery Service REST API operations reference
- Resource reference for the Mail, Calendar, Contacts, and Task REST APIs