Use the Microsoft Search API to search Outlook messages
Use the Microsoft Search API in Microsoft Graph to search for information in email messages, return messages ranked by relevance, and render a dedicated search experience. The search applies to the body and attachments of messages in the signed-in user's own mailbox.
Caution
The search API schema has changed in the beta version. Some properties in a search request and response have been renamed or removed. For details, see Schema change deprecation warning. The examples in this topic show the up-to-date schema.
A search query can include filters that end users enter in the Search text box in Outlook.
Message search results are sorted by receivedDateTime in descending order.
Message search applies to work or school accounts. Users can search their own mailbox, but can't search delegated mailboxes. For details, see known limitations.
Message search also looks for attachments. The supported file types for message attachment search are the same as those for SharePoint Online search.
Example 1: Search messages in a user's mailbox
The following example queries messages in the signed-in user's mailbox that contain the string "contoso" in any part of the message (the sender name, subject, message body, or any attachments). The query returns the first 25 results. The search results are ordered by DateTime descending.
Request
POST https://graph.microsoft.com/v1.0/search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"message"
],
"query": {
"queryString": "contoso"
},
"from": 0,
"size": 25
}
]
}
Response
The following is an example of the response, which contains one message that matches the search criterion.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#search",
"value": [
{
"searchTerms": [
"contoso"
],
"hitsContainers": [
{
"total": 1,
"moreResultsAvailable": false,
"hits": [
{
"hitId": "ptWLQ4o6HYpQg8xmAAATzOzRAAA=",
"rank": 1,
"summary": "Here is a summary of your messages from last week",
"resource": {
"@odata.type": "#microsoft.graph.message",
"createdDateTime": "2019-10-07T10:00:08Z",
"lastModifiedDateTime": "2019-10-07T10:00:11Z",
"receivedDateTime": "2019-10-07T10:00:09Z",
"sentDateTime": "2019-10-07T09:59:52Z",
"hasAttachments": false,
"subject": "Weekly digest: Microsoft 365 changes",
"bodyPreview": "Here is a summary of your messages from last week - New Feature: Live captions in English-US a",
"importance": "normal",
"replyTo": [
{
"emailAddress": {
"name": "Goncalo Torres"
}
}
],
"sender": {
"emailAddress": {
"name": "Office365 Message Center",
"address": "gtorres@contoso.com"
}
},
"from": {
"emailAddress": {
"name": "Office365 Message Center",
"address": "gtorres@contoso.com"
}
}
}
}
]
}
]
}
]
}
Example 2: Search top results messages
The following example uses the search query shown in Example 1, and sorts the results by relevance.
Request
POST https://graph.microsoft.com/v1.0/search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"message"
],
"query": {
"queryString": "contoso"
},
"from": 0,
"size": 15,
"enableTopResults": true
}
]
}
Response
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#search",
"value": [
{
"searchTerms": [
"contoso"
],
"hitsContainers": [
{
"total": 1,
"moreResultsAvailable": false,
"hits": [
{
"hitId": "ptWLQ4o6HYpQg8xmAAATzOzRAAA=",
"rank": 1,
"summary": "Here is a summary of your messages from last week",
"resource": {
"@odata.type": "#microsoft.graph.message",
"createdDateTime": "2019-10-07T10:00:08Z",
"lastModifiedDateTime": "2019-10-07T10:00:11Z",
"receivedDateTime": "2019-10-07T10:00:09Z",
"sentDateTime": "2019-10-07T09:59:52Z",
"hasAttachments": false,
"subject": "Weekly digest: Microsoft 365 changes",
"bodyPreview": "Here is a summary of your messages from last week - New Feature: Live captions in English-US a",
"importance": "normal",
"replyTo": [
{
"emailAddress": {
"name": "Goncalo Torres"
}
}
],
"sender": {
"emailAddress": {
"name": "Office365 Message Center",
"address": "gtorres@contoso.com"
}
},
"from": {
"emailAddress": {
"name": "Office365 Message Center",
"address": "gtorres@contoso.com"
}
}
}
}
]
}
]
}
]
}
Known limitations
- You can access only the signed-in user’s own mailbox. Searching delegated mailboxes is not supported.
- For messages, the total property of the searchHitsContainer type contains the number of results on the page, not the total number of matching results.
- Sorting results is not supported for events. A sort clause in the request will return a Bad Request error code in the response.