List messages

Get the messages in the signed-in user's mailbox (including the Deleted Items and Clutter folders).

In particular, you can filter on the messages and get only those that include a mention of the signed-in user.

Note that by default, the GET /me/messages operation does not return the mentions property. Use the $expand query parameter to find details of each mention in a message.

Prerequisites

One of the following scopes is required to execute this API: Mail.Read; Mail.ReadWrite

HTTP request

To get all the messages in a user's mailbox:

GET /me/messages
GET /users/{id | userPrincipalName}/messages

To get messages in a specific folder in the user's mailbox:

GET /me/mailFolders/{id}/messages
GET /users/{id | userPrincipalName}/mailFolders/{id}/messages

To get all the messages in the user's mailbox that include a mention of the user:

GET /me/messages?$filter=mentionsPreview/isMentioned eq true
GET /users/{id | userPrincipalName}/messages?$filter=mentionsPreview/isMentioned eq true

Optional query parameters

This method supports the OData Query Parameters to help customize the response.

You can use the $filter query parameter on the mentionsPreview property to get those messages that mention the signed-in user.

Request headers

Header Value
Authorization Bearer . Required.
Content-Type application/json

Request body

Do not supply a request body for this method.

Response

If successful, this method returns a 200 OK response code and collection of message objects in the response body.

The default page size for this request is 10 messages.

Example

Request 1

The first example gets the top 10 messages in the signed-in user's mailbox.

GET https://graph.microsoft.com/beta/me/messages
Response 1

Here is an example of the response. Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

HTTP/1.1 200 OK
Content-type: application/json
Content-length: 317

{
  "value": [
    {
      "receivedDateTime": "2016-10-19T10:37:00Z",
      "sentDateTime": "2016-10-19T10:37:00Z",
      "hasAttachments": true,
      "subject": "subject-value",
      "body": {
        "contentType": "",
        "content": "content-value"
      },
      "bodyPreview": "bodyPreview-value"
    }
  ]
}
Request 2

The next example 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.

The example also incorporates URL encoding for the space characters in the query parameter string.

GET https://graph.microsoft.com/beta/me/messages?$filter=MentionsPreview/IsMentioned%20eq%20true&$select=Subject,Sender,ReceivedDateTime,MentionsPreview
Response 2

Here is an example of the response. Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

HTTP/1.1 200 OK
Content-type: application/json
Content-length: 987

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#me/messages(subject,sender,receivedDateTime,mentionsPreview)",
  "value":[
    {
      "@odata.id":"https://graph.microsoft.com/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://graph.microsoft.com/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
      }
    }
  ]
}