The Graph API allows the users to search for the messages either by using either $filter query parameter or $search query parameter or /search/query endpoint.
In this article I will focus on the $filter query parameter.
The official documentation doesn't clarify which properties support filtering. It's a great opportunity to find out the current state.
Properties supporting filtering
The table below shows an overview of the message properties supporting filtering. Each property supports only a subset of the query operators.
| Property | eq | ne | le | lt | ge | gt | startsWith | contains | endsWith | not | in | has |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| body/content | - | - | - | - | - | - | YES | YES | - | YES | - | - |
| categories | YES | YES | - | - | - | - | - | - | - | YES | - | - |
| conversationId | YES | YES | - | - | - | - | - | - | - | - | - | - |
| createdDateTime | - | YES | YES | YES | YES | YES | - | - | - | YES | - | - |
| flag/flagStatus | YES | YES | - | - | - | - | - | - | - | - | - | - |
| flag/startDateTime | YES | - | - | - | YES | YES | - | - | - | - | - | - |
| flag/dueDateTime | YES | - | - | - | YES | YES | - | - | - | - | - | - |
| flag/completedDateTime | YES | - | - | - | YES | YES | - | - | - | - | - | - |
| from | YES | YES | - | - | - | - | YES | YES | - | YES | - | - |
| hasAttachments | YES | YES | - | - | - | - | - | - | - | YES | - | - |
| importance | YES | YES | YES | YES | YES | YES | - | - | - | YES | - | - |
| inferenceClassification | YES | YES | YES | YES | YES | YES | - | - | - | YES | - | - |
| internetMessageId | YES | YES | - | - | - | - | YES | YES | - | YES | - | - |
| isDeliveryReceiptRequested | YES | YES | - | - | - | - | - | - | - | YES | - | - |
| isDraft | YES | YES | - | - | - | - | - | - | - | YES | - | - |
| isRead | YES | YES | - | - | - | - | - | - | - | YES | - | - |
| isReadReceiptRequested | YES | YES | - | - | - | - | - | - | - | YES | - | - |
| lastModifiedDateTime | - | YES | YES | YES | YES | YES | - | - | - | YES | - | - |
| parentFolderId | YES | YES | - | - | - | - | - | - | - | YES | - | - |
| receivedDateTime | - | YES | YES | YES | YES | YES | - | - | - | YES | - | - |
| sender/emailAddress/address | YES | YES | - | - | - | - | YES | YES | - | YES | - | - |
| sender/emailAddress/name | YES | YES | - | - | - | - | YES | YES | - | YES | - | - |
| sentDateTime | YES | YES | YES | YES | YES | YES | - | - | - | YES | - | - |
| subject | YES | YES | - | - | - | - | YES | YES | - | YES | - | - |
Examples
Check examples how to filter messages by each property mentioned above.
body
GET v1.0/me/messages?$filter=startsWith(body/content,'Hello')
GET v1.0/me/messages?$filter=not(startswith(body/content,'Hello'))
GET v1.0/me/messages?$filter=contains(body/content,'meeting')
GET v1.0/me/messages?$filter=not(contains(body/content,'Hello'))
categories
GET v1.0/me/messages?$filter=categories/any(c:c eq 'Urgent')
GET v1.0/me/messages?$filter=categories/any(c:c ne 'Urgent')
GET v1.0/me/messages?$filter=not(categories/any(c:c eq 'Urgent'))
conversationId
GET v1.0/me/messages?$filter=conversationId eq 'AAQkAGRkZTFiMDQxLWYzNDgtNGQ3ZS05Y2U3LWU1NWJhMTM5YTgwMAAQAM4713wb5UW-sXYNpR4Qdws='
GET v1.0/me/messages?$filter=conversationId ne 'AAQkAGRkZTFiMDQxLWYzNDgtNGQ3ZS05Y2U3LWU1NWJhMTM5YTgwMAAQAM4713wb5UW-sXYNpR4Qdws='
GET v1.0/me/messages?$filter=not(conversationId ne 'AAQkAGRkZTFiMDQxLWYzNDgtNGQ3ZS05Y2U3LWU1NWJhMTM5YTgwMAAQAM4713wb5UW-sXYNpR4Qdws=')
createdDateTime
GET v1.0/me/messages?$filter=createdDateTime ge 2023-06-26T11:54:31Z
GET v1.0/me/messages?$filter=createdDateTime ge 2023-06-26
GET v1.0/me/messages?$filter=createdDateTime gt 2023-06-26T11:54:31Z
GET v1.0/me/messages?$filter=createdDateTime gt 2023-06-26
GET v1.0/me/messages?$filter=createdDateTime le 2023-06-26T11:54:31Z
GET v1.0/me/messages?$filter=createdDateTime le 2023-06-26
GET v1.0/me/messages?$filter=createdDateTime lt 2023-06-26T11:54:31Z
GET v1.0/me/messages?$filter=createdDateTime lt 2023-06-26
GET v1.0/me/messages?$filter=createdDateTime ne 2023-06-26T11:54:31Z
GET v1.0/me/messages?$filter=createdDateTime ne 2023-06-26
GET v1.0/me/messages?$filter=not(createdDateTime lt 2023-06-26T11:54:31Z)
GET v1.0/me/messages?$filter=not(createdDateTime lt 2023-06-26)
flag
GET v1.0/me/messages?$filter=flag/flagStatus eq 'notFlagged'
GET v1.0/me/messages?$filter=flag/flagStatus ne 'notFlagged'
GET v1.0/me/messages?$filter=flag/startDateTime/dateTime ge '2015-02-17T23:00:00.0000000'
GET v1.0/me/messages?$filter=flag/startDateTime/dateTime eq '2015-02-17T23:00:00.0000000'
GET v1.0/me/messages?$filter=flag/startDateTime/dateTime gt '2015-02-17T23:00:00.0000000'
GET v1.0/me/messages?$filter=flag/dueDateTime/dateTime ge '2015-02-17T23:00:00.0000000'
GET v1.0/me/messages?$filter=flag/dueDateTime/dateTime eq '2015-02-17T23:00:00.0000000'
GET v1.0/me/messages?$filter=flag/dueDateTime/dateTime gt '2015-02-17T23:00:00.0000000'
GET v1.0/me/messages?$filter=flag/completedDateTime/dateTime ge '2015-02-17T23:00:00.0000000'
GET v1.0/me/messages?$filter=flag/completedDateTime/dateTime eq '2015-02-17T23:00:00.0000000'
GET v1.0/me/messages?$filter=flag/completedDateTime/dateTime gt '2015-02-17T23:00:00.0000000'
from
GET v1.0/me/messages?$filter=from/emailAddress/address eq 'adele.vence@contoso.com'
GET v1.0/me/messages?$filter=from/emailAddress/address ne 'adele.vence@contoso.com'
GET v1.0/me/messages?$filter=startsWith(from/emailAddress/address,'adele')
GET v1.0/me/messages?$filter=contains(from/emailAddress/address,'cox.net')
GET v1.0/me/messages?$filter=not(from/emailAddress/address ne 'adele.vence@contoso.com')
hasAttachments
GET v1.0/me/messages?$filter=hasAttachments eq true
GET v1.0/me/messages?$filter=hasAttachments ne true
GET v1.0/me/messages?$filter=not(hasAttachments eq true)
importance
GET v1.0/me/messages?$filter=importance eq 'normal'
GET v1.0/me/messages?$filter=importance ne 'normal'
GET v1.0/me/messages?$filter=not(importance eq 'normal')
GET v1.0/me/messages?$filter=importance ne 'low' and importance ne 'normal'
GET v1.0/me/messages?$filter=importance le 'normal'
GET v1.0/me/messages?$filter=importance lt 'normal'
GET v1.0/me/messages?$filter=importance ge 'normal'
GET v1.0/me/messages?$filter=importance gt 'normal'
inferenceClassification
GET v1.0/me/messages?$filter=inferenceClassification eq 'focused'
GET v1.0/me/messages?$filter=inferenceClassification eq 'other'
GET v1.0/me/messages?$filter=inferenceClassification ne 'focused'
GET v1.0/me/messages?$filter=not(inferenceClassification ne 'focused')
GET v1.0/me/messages?$filter=inferenceClassification le 'focused'
GET v1.0/me/messages?$filter=inferenceClassification lt 'focused'
GET v1.0/me/messages?$filter=inferenceClassification ge 'focused'
GET v1.0/me/messages?$filter=inferenceClassification gt 'focused'
internetMessageId
GET v1.0/me/messages?$filter=internetMessageId eq '<networks/1847689/messages/2333039863414784@yammer.com.649d4f26f7dd_49a3fe9699fa10440102cd>'
GET v1.0/me/messages?$filter=internetMessageId ne '<networks/1847689/messages/2333039863414784@yammer.com.649d4f26f7dd_49a3fe9699fa10440102cd>'
GET v1.0/me/messages?$filter=not(internetMessageId ne '<networks/1847689/messages/2333039863414784@yammer.com.649d4f26f7dd_49a3fe9699fa10440102cd>')
GET v1.0/me/messages?$filter=startsWith(internetMessageId,'<networks/1847689/messages/2')
GET v1.0/me/messages?$filter=contains(internetMessageId,'yammer.com')
isDeliveryReceiptRequested
GET v1.0/me/messages?$filter=isDeliveryReceiptRequested eq true
GET v1.0/me/messages?$filter=isDeliveryReceiptRequested ne false
GET v1.0/me/messages?$filter=not(isDeliveryReceiptRequested ne false)
isDraft
GET v1.0/me/messages?$filter=isDraft eq true
GET v1.0/me/messages?$filter=isDraft ne false
GET v1.0/me/messages?$filter=not(isDraft ne false)
isRead
GET v1.0/me/messages?$filter=isRead eq true
GET v1.0/me/messages?$filter=isRead ne false
GET v1.0/me/messages?$filter=not(isRead ne false)
isReadReceiptRequested
GET v1.0/me/messages?$filter=isReadReceiptRequested eq true
GET v1.0/me/messages?$filter=isReadReceiptRequested ne false
GET v1.0/me/messages?$filter=not(isReadReceiptRequested ne false)
lastModifiedDateTime
GET v1.0/me/messages?$filter=lastModifiedDateTime ge 2023-06-29T08:19:33Z
GET v1.0/me/messages?$filter=lastModifiedDateTime ge 2023-06-29
GET v1.0/me/messages?$filter=lastModifiedDateTime gt 2023-06-29T08:19:33Z
GET v1.0/me/messages?$filter=lastModifiedDateTime gt 2023-06-29
GET v1.0/me/messages?$filter=lastModifiedDateTime le 2023-06-29T08:19:33Z
GET v1.0/me/messages?$filter=lastModifiedDateTime le 2023-06-29
GET v1.0/me/messages?$filter=lastModifiedDateTime lt 2023-06-29T08:19:33Z
GET v1.0/me/messages?$filter=lastModifiedDateTime lt 2023-06-29
GET v1.0/me/messages?$filter=lastModifiedDateTime ne 2023-06-29T08:19:33Z
GET v1.0/me/messages?$filter=lastModifiedDateTime ne 2023-06-29
parentFolderId
GET v1.0/me/messages?$filter=parentFolderId eq 'AAMkAGRkZTFiMDQxLWYzNDgtNGQ3ZS05Y2U3LWU1NWJhMTM5YTgwMAAuAAAAAABxI4iNfZK7SYRiWw9sza20AQACAd7HWUedTo-i2ZIVhDiHAALcwVSzAAA='
GET v1.0/me/messages?$filter=parentFolderId ne 'AAMkAGRkZTFiMDQxLWYzNDgtNGQ3ZS05Y2U3LWU1NWJhMTM5YTgwMAAuAAAAAABxI4iNfZK7SYRiWw9sza20AQACAd7HWUedTo-i2ZIVhDiHAALcwVSzAAA='
GET v1.0/me/messages?$filter=not(parentFolderId ne 'AAMkAGRkZTFiMDQxLWYzNDgtNGQ3ZS05Y2U3LWU1NWJhMTM5YTgwMAAuAAAAAABxI4iNfZK7SYRiWw9sza20AQACAd7HWUedTo-i2ZIVhDiHAALcwVSzAAA=')
receivedDateTime
GET v1.0/me/messages?$filter=receivedDateTime ge 2023-06-29T08:19:33Z
GET v1.0/me/messages?$filter=receivedDateTime ge 2023-06-29
GET v1.0/me/messages?$filter=receivedDateTime gt 2023-06-29T08:19:33Z
GET v1.0/me/messages?$filter=receivedDateTime gt 2023-06-29
GET v1.0/me/messages?$filter=receivedDateTime lt 2023-06-29T08:19:33Z
GET v1.0/me/messages?$filter=receivedDateTime lt 2023-06-29
GET v1.0/me/messages?$filter=receivedDateTime le 2023-06-29T08:19:33Z
GET v1.0/me/messages?$filter=receivedDateTime le 2023-06-29
GET v1.0/me/messages?$filter=receivedDateTime ne 2023-06-29T08:19:33Z
GET v1.0/me/messages?$filter=receivedDateTime ne 2023-06-29
sender/emailaddress/address
GET v1.0/me/messages?$filter=sender/emailaddress/address eq 'adele.vence@contoso.com'
GET v1.0/me/messages?$filter=sender/emailaddress/address ne 'adele.vence@contoso.com'
GET v1.0/me/messages?$filter=startsWith(sender/emailAddress/address,'adel')
GET v1.0/me/messages?$filter=contains(sender/emailAddress/address,'google')
sender/emailaddress/name
GET v1.0/me/messages?$filter=sender/emailaddress/address eq 'account-verification-noreply@google.com'
GET v1.0/me/messages?$filter=sender/emailaddress/address ne 'account-verification-noreply@google.com'
GET v1.0/me/messages?$filter=startsWith(sender/emailAddress/name,'account-verification')
GET v1.0/me/messages?$filter=contains(sender/emailaddress/name,'google.com')
sentDateTime
GET v1.0/me/messages?$filter=sentDateTime eq 2013-05-02T06:16:31Z
GET v1.0/me/messages?$filter=sentDateTime eq 2013-05-02
GET v1.0/me/messages?$filter=sentDateTime ne 2013-05-02T06:16:31Z
GET v1.0/me/messages?$filter=sentDateTime ne 2013-05-02
GET v1.0/me/messages?$filter=sentDateTime ge 2023-05-02T06:16:31Z
GET v1.0/me/messages?$filter=sentDateTime ge 2023-05-02
GET v1.0/me/messages?$filter=sentDateTime gt 2023-05-02T06:16:31Z
GET v1.0/me/messages?$filter=sentDateTime gt 2023-05-02
GET v1.0/me/messages?$filter=sentDateTime le 2023-05-02T06:16:31Z
GET v1.0/me/messages?$filter=sentDateTime le 2023-05-02
GET v1.0/me/messages?$filter=sentDateTime lt 2023-05-02T06:16:31Z
GET v1.0/me/messages?$filter=sentDateTime lt 2023-05-02
GET v1.0/me/messages?$filter=not(sentDateTime le 2023-05-02T06:16:31Z)
subject
GET v1.0/me/messages?$filter=subject eq 'Secret'
GET v1.0/me/messages?$filter=subject ne 'Secret'
GET v1.0/me/messages?$filter=not(subject ne 'Secret')
GET v1.0/me/messages?$filter=startswith(subject,'vacation')
GET v1.0/me/messages?$filter=contains(subject,'help')
Properties not supporting filtering
The table below shows an overview of the message properties not supporting filtering.
| Property |
|---|
| bccRecipients |
| bodyPreview |
| body/contentType |
| ccRecipients |
| changeKey |
| conversationIndex |
| id |
| internetMessageHeaders |
| replyTo |
| toRecipients |
| uniqueBody |
| webLink |
Conclusion
The $filter query parameter supports most of the properties but using more properties in the filter can lead to a complicated filter query.
The advantage is that the filter's syntax is the same as for another collections and most users are familiar with this syntax.
In the next blog post, I will focus on $search query parameter.
