In the previous articles, I explained how to use the $filter and the $search query parameters for filtering/searching messages.
The third way to search for information in email messages, is by using the Microsoft Search API.
The Search API
The Microsoft Search API can be accessed through the /search/query endpoint.
POST https://graph.microsoft.com/v1.0/search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"message"
],
"query": {
"queryString": "contoso"
},
"fields": [
"id",
"subject",
"body"
]
"from": 0,
"size": 25
}
]
}
The request body defines the type of the resource to be searched, the fields to be returned, the query terms, or the size of the page to be retrieved.
The query/queryString defines the search query containing the search terms.
Properties supporting searching
The table below shows an overview of the message properties supporting searching. During the searching you need to use a specific keyword related to each property in the query/queryString.
| Property | Search keyword(s) | Is default |
|---|---|---|
| bccRecipients | bcc, participants, recipients | - |
| body | body | YES |
| bodyPreview | body | YES |
| categories | category | - |
| ccRecipients | cc, participants, recipients | - |
| from | from, participants | YES |
| hasAttachments | hasAttachment, hasAttachments | - |
| importance | importance | - |
| isRead | isRead | - |
| receivedDateTime | received | - |
| sender | from | - |
| sentDateTime | sent | - |
| subject | subject | YES |
| toRecipients | to, participants, recipients | - |
| uniqueBody | body | YES |
Search keywords
Before we start exploring each search keyword, check supported search operators
- AND - all of the keywords or the expressions must match
- OR - one or more of the keywords or the expressions must match
- NOT - exclude messages that match the keyword or the expression
- < - property value is less than the specified value
- > - property value is greater than the specified value
- <= - property value is less than or equal to the specified value
- >= - property value is greater than or equal to the specified value
- .. - property value is greater than or equal to the value on the left side and less than or equal to the value on the right side
Default search
When no search keyword is specified, the search is carried out on the default search properties of from, subject, and body.
Search for messages that contains the term "testing" either in the subject, body, or in the email address or the name of the sender.
"queryString": "testing"
Keyword bcc
Search for the specified term in the bccRecipients property.
Search for the exact email addres
"queryString": "bcc:MeetingRoom@contoso.com"
Search for the exact display name
"queryString": "bcc:Room 5.5 (6 seats)"
Keyword body
Search for the specified term in the body property.
Messages with the term "uml" on the body
"queryString": "body:uml"
Messages with the terms "uml" and "interface" in the body
"queryString": "body:uml interface"
Messages that contain a word starting with "presen" in the body
"queryString": "body:presen*"
Messages that contain the exact phrase
"queryString": "body:\"automation testing\""
Keyword category
The categories to search.
Messagess with "Urgent" category
"queryString": "category:Urgent"
Messages with "Urgent" and "Pending" category
"queryString": "category:Urgent Pending"
Messages with either "Urgent" or "Pending" category
"queryString": "category:Urgent OR Pending"
Keyword cc
Search for the recipient in the ccRecipients property.
"queryString": "cc:adele.vence@contoso.com"
"queryString": "cc:Adele Vence"
Keyword from
Search for the sender in the from and the sender properties.
"queryString": "from:Adele Vence"
"queryString": "from:adele.vence@contoso.com"
"queryString": "from:google.com"
Keyword hasAttachment
Alternate search keyword is hasAttachments.
Messages without the attachments
"queryString": "hasAttachments:false"
"queryString": "hasAttachments:no"
Messages with the attachments
"queryString": "hasAttachments:true"
"queryString": "hasAttachments:yes"
Exclude messages without the attachments. NOT operator is case sensitive (alternate operator is -)
"queryString": "NOT hasAttachments:false"
"queryString": "-hasAttachments:false"
Keyword importance
Search for messages with the specified importance
"queryString": "importance:low"
"queryString": "importance>=low"
"queryString": "importance>low"
"queryString": "importance<=high"
"queryString": "importance<high"
Keyword isRead
Search for messages that have been read
"queryString": "isread:yes"
"queryString": "isread:true"
Search for messages that have not been read
"queryString": "isread:no"
"queryString": "isread:false"
Keyword kind
Search for the emails
"queryString": "kind:email"
Search for the instant messaging conversations (including Skype for Business conversations and chats in Microsoft Teams)
"queryString": "kind:im"
Search for the meetings
"queryString": "kind:meetings"
Search for the items from chats, meetings, and calls in Microsoft Teams
"queryString": "kind:microsoftteams"
Search for the items from the OneNote
"queryString": "kind:notes"
The possible values are contacts, docs, email, externaldata, faxes, im, journals, meetings, microsoftteams, notes, posts, rssfeeds, tasks, or voicemail.
Keyword participants
Search for the participant in the from, sender, bccRecipients, ccRecipients and toRecipients properties.
"queryString": "participants:google"
"queryString": "participants:do*"
Keyword recipients
Search for the recipient in the bccRecipients, ccRecipients and toRecipients properties.
"queryString": "recipients:google"
"queryString": "recipients:do*"
Keyword received
Supported datetime formats are:
- YYYY-MM-DD
- YYYY-MM-DDThh:mm:ss
- YYYY-MM-DDThh:mm:ssZ
- MM/DD/YYYY
Search for messages received at the specific day
"queryString": "received:2023-07-05"
"queryString": "received:07/04/2023"
Search for messages received between two dates
"queryString": "received:2023-07-01..2023-07-04"
"queryString": "received:07/01/2023..07/04/2023"
"queryString": "received>=2023-07-01 AND received<=2023-07-03"
"queryString": "received:2023-07-01..2023-07-04"
"queryString": "received:07/01/2023..07/04/2023"
"queryString": "received>=2023-07-01 AND received<=2023-07-03"
"queryString": "received>=07/01/2023 AND received<=07/04/2023"
Instead of the date and time, you can use one of the keywords reserved for the date interval:
- today - the time from the beginning of the current day until the end of the current day
- yesterday - the time from the beginning of the day until the end of the day that precedes the current day
- this week - the time from the beginning of the current week until the end of the current week
- last week - the entire week that precedes the current week
- this month - the time from the beginning of the current month until the end of the current month
- last month - the entire month that precedes the current month
- this year - the time from the beginning of the current year until the end of the current year
- last year - the entire year that precedes the current year
"queryString": "received:today"
"queryString": "received:yesterday"
"queryString": "received:\"this week\""
"queryString": "received:\"last week\""
"queryString": "received:\"this month\""
"queryString": "received:\"last month\""
"queryString": "received:\"this year\""
"queryString": "received:\"last year\""
Keyword sent
The same datetime format and reserved keywords as for received.
"queryString": "sent:2023-07-01..2023-07-04"
"queryString": "sent:07/01/2023..07/04/2023"
"queryString": "sent>=2023-07-01 AND sent<=2023-07-03"
"queryString": "sent>=07/01/2023 AND sent<=07/04/2023"
"queryString": "sent:today"
"queryString": "sent:yesterday"
"queryString": "sent:\"this week\""
"queryString": "sent:\"last week\""
"queryString": "sent:\"this month\""
"queryString": "sent:\"last month\""
"queryString": "sent:\"this year\""
"queryString": "sent:\"last year\""
Keyword subject
Search for messages that contain a specific word
"queryString": "subject:testing"
Search for messages that contain an exact phrase
"queryString": "subject:\"automation testing\""
Keyword size
The size keyword allows to search messages by their size
Search for messages that are larger than 25MB
"queryString": "size>26214400"
Search for messages with the size between 1MB and 10MB
"queryString": "size:1048576..10485760"
Instead of the size, you can use one of the keywords reserved for the size of the message:
- tiny - Items whose size is less than 10 kilobytes
- small - Items whose size is between 10 and 25 kilobytes
- medium - Items whose size is between 25 and 100 kilobytes
- large - Items whose size is between 100 and 500 kilobytes
- very large - Items whose size is between 500 kilobytes and 1 megabyte
- enormous - Items whose size is larger than 5 megabytes
"queryString": "size:tiny"
"queryString": "size:small"
"queryString": "size:medium"
"queryString": "size:large"
"queryString": "size:\"very large\""
"queryString": "size:enormous"
Keyword attachment
The attachment keyword allows to search messages that have an attached file with a name matching the specific value. The alternate keyword is attachmentnames.
Search for messages with "zip" attachments
"queryString": "attachment:*.zip"
"queryString": "attachmentnames:*.zip"
Search for messages that have an attached file with a name "database"
"queryString": "attachment:database"
"queryString": "attachmentnames:database"
Properties not supporting searching
The table below shows an overview of the message properties not supporting filtering.
| Property |
|---|
| changeKey |
| conversationId |
| conversationIndex |
| createdDateTime |
| flag |
| id |
| inferenceClassification |
| internetMessageHeaders |
| internetMessageId |
| isDeliveryReceiptRequested |
| isDraft |
| isReadReceiptRequested |
| lastModifiedDateTime |
| parentFolderId |
| replyTo |
| webLink |
Conclusion
The /search/query endpoint provides the similar searching as the $search query parameter. On both cases the keywords are very similar. Comparing to $filter query parameter the syntax for queryString query parameter is less verbose and the query is more readable for the users. Reserved keywords allow us to avoid writing a complex condition.
On the other hand, the /search/query support less message properties than the $filter.
