In the previous post, I explained how to use the $filter query parameter for filtering messages.
The second way how you can search messages based on a value in specific message properties is by using the $search query parameter.
The syntax for $search is a little bit different than for $filter.
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.
| 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.
GET v1.0/me/messages?$search="testing"
Keyword bcc
Search for the specified term in the bccRecipients property.
Search for the exact email addres
GET v1.0/me/messages?$search="bcc:MeetingRoom@contoso.com"
Search for the exact display name
GET v1.0/me/messages?$search="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
GET v1.0/me/messages?$search="body:uml"
Messages with the terms "uml" and "interface" in the body
GET v1.0/me/messages?$search="body:uml interface"
Messages that contain a word starting with "presen" in the body
v1.0/me/messages?$search="body:presen*"
Messages that contain the exact phrase
GET v1.0/me/messages?$search="body:\"automation testing\""
Keyword category
The categories to search.
Messagess with "Urgent" category
GET v1.0/me/messages?$search="category:Urgent"
Messages with "Urgent" and "Pending" category
GET v1.0/me/messages?$search="category:Urgent Pending"
Messages with either "Urgent" or "Pending" category
GET v1.0/me/messages?$search="category:Urgent OR Pending"
Keyword cc
Search for the recipient in the ccRecipients property.
GET v1.0/me/messages?$search="cc:adele.vence@contoso.com"
GET v1.0/me/messages?$search="cc:Adele Vence"
Keyword from
Search for the sender in the from and the sender properties.
GET v1.0/me/messages?$search="from:Adele Vence"
GET v1.0/me/messages?$search="from:adele.vence@contoso.com"
GET v1.0/me/messages?$search="from:google.com"
Keyword hasAttachment
Alternate search keyword is hasAttachments.
Messages without the attachments
GET v1.0/me/messages?$search="hasAttachments:false"
GET v1.0/me/messages?$search="hasAttachments:no"
Messages with the attachments
GET v1.0/me/messages?$search="hasAttachments:true"
GET v1.0/me/messages?$search="hasAttachments:yes"
Exclude messages without the attachments. NOT operator is case sensitive (alternate operator is -)
GET v1.0/me/messages?$search="NOT hasAttachments:false"
GET v1.0/me/messages?$search="-hasAttachments:false"
Keyword importance
Search for messages with the specified importance
GET v1.0/me/messages?$search="importance:low"
GET v1.0/me/messages?$search="importance>=low"
GET v1.0/me/messages?$search="importance>low"
GET v1.0/me/messages?$search="importance<=high"
GET v1.0/me/messages?$search="importance<high"
Keyword isRead
Search for messages that have been read
GET v1.0/me/messages?$search="isread:yes"
GET v1.0/me/messages?$search="isread:true"
Search for messages that have not been read
GET v1.0/me/messages?$search="isread:no"
GET v1.0/me/messages?$search="isread:false"
Keyword kind
Search for the emails
GET v1.0/me/messages?$search="kind:email"
Search for the conversations in history
GET v1.0/me/messages?$search="kind:im"
Search for the event messages
GET v1.0/me/messages?$search="kind:meetings"
The possible values are contacts, docs, email, faxes, im, journals, meetings, notes, posts, rssfeeds, tasks, or voicemail.
Keyword participants
Search for the participant in the from, sender, bccRecipients, ccRecipients and toRecipients properties.
GET v1.0/me/messages?$search="participants:google"
GET v1.0/me/messages?$search="participants:do*"
Keyword recipients
Search for the recipient in the bccRecipients, ccRecipients and toRecipients properties.
GET v1.0/me/messages?$search="recipients:google"
GET v1.0/me/messages?$search="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
GET v1.0/me/messages?$search="received:2023-07-03"
GET v1.0/me/messages?$search="received:07/03/2023"
Search for messages received between two dates
GET v1.0/me/messages?$search="received:2023-07-01..2023-07-04"
GET v1.0/me/messages?$search="received:07/01/2023..07/04/2023"
GET v1.0/me/messages?$search="received>=2023-07-01 AND received<=2023-07-03"
GET v1.0/me/messages?$search="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
GET v1.0/me/messages?$search="received:today"
GET v1.0/me/messages?$search="received:yesterday"
GET v1.0/me/messages?$search="received:\"this week\""
GET v1.0/me/messages?$search="received:\"last week\""
GET v1.0/me/messages?$search="received:\"this month\""
GET v1.0/me/messages?$search="received:\"last month\""
GET v1.0/me/messages?$search="received:\"this year\""
GET v1.0/me/messages?$search="received:\"last year\""
Keyword sent
The same datetime format and reserved keywords as for received.
GET v1.0/me/messages?$search="sent:2023-07-01..2023-07-04"
GET v1.0/me/messages?$search="sent:07/01/2023..07/04/2023"
GET v1.0/me/messages?$search="sent>=2023-07-01 AND sent<=2023-07-03"
GET v1.0/me/messages?$search="sent>=07/01/2023 AND sent<=07/04/2023"
GET v1.0/me/messages?$search="sent:today"
GET v1.0/me/messages?$search="sent:yesterday"
GET v1.0/me/messages?$search="sent:\"this week\""
GET v1.0/me/messages?$search="sent:\"last week\""
GET v1.0/me/messages?$search="sent:\"this month\""
GET v1.0/me/messages?$search="sent:\"last month\""
GET v1.0/me/messages?$search="sent:\"this year\""
GET v1.0/me/messages?$search="sent:\"last year\""
Keyword subject
Search for messages that contain a specific word
GET v1.0/me/messages?$search="subject:testing"
Search for messages that contain an exact phrase
GET v1.0/me/messages?$search="subject:\"automation testing\""
Keyword size
The size keyword allows to search messages by their size
Search for messages that are larger than 25MB
GET v1.0/me/messages?$search="size>26214400"
Search for messages with the size between 1MB and 10MB
GET v1.0/me/messages?$search="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
GET v1.0/me/messages?$search="size:tiny"
GET v1.0/me/messages?$search="size:small"
GET v1.0/me/messages?$search="size:medium"
GET v1.0/me/messages?$search="size:large"
GET v1.0/me/messages?$search="size:\"very large\""
GET v1.0/me/messages?$search="size:enormous"
Keyword attachment
The attachment keyword allows to search messages that have an attached file with a name matching the specific value
Search for messages with "zip" attachments
GET v1.0/me/messages?$search="attachment:*.zip"
Search for messages that have an attached file with a name "database"
GET v1.0/me/messages?$search="attachment: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 parameter provides a powerful way how to search messages. Comparing to $filter query parameter the syntax for $search 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 support less message properties than the $filter. The disavantage is that the $search doesn't return an error in case of wrong syntax or wrong keyword.
In the next blog post, I will focus on the /search/query endpoint.
