[DEPRECATED] Outlook Mail REST API reference (beta)

  • Makale

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.

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 skipToken that 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:

  1. 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.)

  2. If the first response returns the Preference-Applied: odata.track-changes header, you can proceed with synchronizing the folder.

  3. 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.

  4. 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:

  1. 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.

  2. 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 deltaLink and deltaToken.
  • The second request uses that deltaToken. The second response returns 2 messages, a nextLink and skipToken.
  • To complete the sync, the third and fourth requests use the skipToken returned from the previous sync request, until the fourth sync response returns a deltaLink and deltaToken, in which case this round of sync is complete. Save the deltaToken for 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

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 Message parameter. 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 Message parameter. 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 Message parameter. 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 Message parameter. 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 Message parameter. Specifying both will return an HTTP 400 Bad Request error.
  • You must specify either the ToRecipients parameter or the ToRecipients property of the Message parameter. 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 Message parameter. Specifying both will return an HTTP 400 Bad Request error.
  • You must specify either the ToRecipients parameter or the ToRecipients property of the Message parameter. 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

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&nbsp;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

MailboxSettings.

To get just the preferred language setting among all mailbox settings:

GET https://outlook.office.com/api/beta/me/MailboxSettings/Language

Response type

LocaleInfo.

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

AutomaticRepliesSetting.

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

MailboxSettings.

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: