How to create a mail search folder using the Graph API

11/09/2024
mailGraph APImail search folder

Mail search folder

A mailSearchFolder is a virtual folder in the user's mailbox that contains messages matching predefined search criteria. Search folders can be created in any folder in a user's Exchange Online mailbox.

If the search folder is created in the WellKnownFolderName.SearchFolders folder then it will appear in Outlook for Desktop or Outlook for the web. Otherwise, the search folder will be accessible only through the Graph API.

Search folders will expire after 45 days of no usage. If you exceed the limit of created search folders, older search folders are deleted. You can create at least 50 search folders.

Create a mail search folder

When creating a new mail search folder, you need to specify the source mailbox folders that should be searched, whether the nested mail folders should be searched and last but not least, the OData query to filter messages that should appear in the mail search folder.

POST /users/{id}/mailFolders/searchfolders/childFolders

{
    "@odata.type": "microsoft.graph.mailSearchFolder",
    "displayName": "My custom search mail folder",
    "includeNestedFolders": true,
    "sourceFolderIds": [
        "{mail_folder_id}"
    ],
    "filterQuery": "contains(subject, 'project Threadstone') AND sentDateTime ge 2024-08-01 AND sentDateTime le 2024-08-31"
}

The table below shows an overview of the message properties that support 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/emailAddress/address YES YES - - - - YES YES - YES - -
from/emailAddress/name 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 - -
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 (only the filterQuery property from the request object is shown for readability).

body

"filterQuery": "startsWith(body/content,'Project Threadstone')"
"filterQuery": "not(startswith(body/content,'Project'))"
"filterQuery": "contains(body/content,'threadstone')"
"filterQuery": "not(contains(body/content,'impossible'))"

categories

"filterQuery": "categories/any(c:c eq 'Urgent')"
"filterQuery": "categories/any(c:c ne 'Urgent')"
"filterQuery": "not(categories/any(c:c eq 'Urgent'))"

conversationId

"filterQuery": "conversationId eq 'AAQkAGRkZTFiMDQxLWYzNDgtNGQ3ZS05Y2U3LWU1NWJhMTM5YTgwMAAQAM4713wb5UW-sXYNpR4Qdws='"
"filterQuery": "conversationId ne 'AAQkAGRkZTFiMDQxLWYzNDgtNGQ3ZS05Y2U3LWU1NWJhMTM5YTgwMAAQAM4713wb5UW-sXYNpR4Qdws='"
"filterQuery": "not(conversationId ne 'AAQkAGRkZTFiMDQxLWYzNDgtNGQ3ZS05Y2U3LWU1NWJhMTM5YTgwMAAQAM4713wb5UW-sXYNpR4Qdws=')"

createdDateTime

"filterQuery": "createdDateTime ge 2024-06-26T11:54:31Z"
"filterQuery": "createdDateTime ge 2024-06-26"
"filterQuery": "createdDateTime gt 2024-06-26T11:54:31Z"
"filterQuery": "createdDateTime gt 2024-06-26"
"filterQuery": "createdDateTime le 2024-06-26T11:54:31Z"
"filterQuery": "createdDateTime le 2024-06-26"
"filterQuery": "createdDateTime lt 2024-06-26T11:54:31Z"
"filterQuery": "createdDateTime lt 2024-06-26"
"filterQuery": "createdDateTime ne 2024-06-26T11:54:31Z"
"filterQuery": "createdDateTime ne 2024-06-26"
"filterQuery": "not(createdDateTime lt 2024-06-26T11:54:31Z)"
"filterQuery": "not(createdDateTime lt 2024-06-26)"

flag

"filterQuery": "flag/flagStatus eq 'notFlagged'"
"filterQuery": "flag/flagStatus ne 'notFlagged'"
"filterQuery": "flag/startDateTime/dateTime ge '2015-02-17T23:00:00.0000000'"
"filterQuery": "flag/startDateTime/dateTime eq '2015-02-17T23:00:00.0000000'"
"filterQuery": "flag/startDateTime/dateTime gt '2015-02-17T23:00:00.0000000'"
"filterQuery": "flag/dueDateTime/dateTime ge '2015-02-17T23:00:00.0000000'"
"filterQuery": "flag/dueDateTime/dateTime eq '2015-02-17T23:00:00.0000000'"
"filterQuery": "flag/dueDateTime/dateTime gt '2015-02-17T23:00:00.0000000'"
"filterQuery": "flag/completedDateTime/dateTime ge '2015-02-17T23:00:00.0000000'"
"filterQuery": "flag/completedDateTime/dateTime eq '2015-02-17T23:00:00.0000000'"
"filterQuery": "flag/completedDateTime/dateTime gt '2015-02-17T23:00:00.0000000'"

from/emailAddress/address

"filterQuery": "from/emailAddress/address eq 'adele.vence@contoso.com'"
"filterQuery": "from/emailAddress/address ne 'adele.vence@contoso.com'"
"filterQuery": "startsWith(from/emailAddress/address,'adele')"
"filterQuery": "contains(from/emailAddress/address,'cox.net')"
"filterQuery": "not(from/emailAddress/address ne 'adele.vence@contoso.com')"

from/emailaddress/name

"filterQuery": "from/emailaddress/name eq 'Microsoft Security'"
"filterQuery": "from/emailaddress/name ne 'Microsoft Security'"
"filterQuery": "startsWith(from/emailAddress/name,'Microsoft')"
"filterQuery": "contains(from/emailaddress/name,'Security')"

hasAttachments

"filterQuery": "hasAttachments eq true"
"filterQuery": "hasAttachments ne true"
"filterQuery": "not(hasAttachments eq true)"

importance

"filterQuery": "importance eq 'normal'"
"filterQuery": "importance ne 'normal'"
"filterQuery": "not(importance eq 'normal')"
"filterQuery": "importance ne 'low' and importance ne 'normal'"
"filterQuery": "importance le 'normal'"
"filterQuery": "importance lt 'normal'"
"filterQuery": "importance ge 'normal'"
"filterQuery": "importance gt 'normal'"

inferenceClassification

"filterQuery": "inferenceClassification eq 'focused'"
"filterQuery": "inferenceClassification eq 'other'"
"filterQuery": "inferenceClassification ne 'focused'"
"filterQuery": "not(inferenceClassification ne 'focused')"
"filterQuery": "inferenceClassification le 'focused'"
"filterQuery": "inferenceClassification lt 'focused'"
"filterQuery": "inferenceClassification ge 'focused'"
"filterQuery": "inferenceClassification gt 'focused'"

internetMessageId

"filterQuery": "internetMessageId eq '<networks/1847689/messages/2333039863414784@yammer.com.649d4f26f7dd_49a3fe9699fa10440102cd>'"
"filterQuery": "internetMessageId ne '<networks/1847689/messages/2333039863414784@yammer.com.649d4f26f7dd_49a3fe9699fa10440102cd>'"
"filterQuery": "not(internetMessageId ne '<networks/1847689/messages/2333039863414784@yammer.com.649d4f26f7dd_49a3fe9699fa10440102cd>')"
"filterQuery": "startsWith(internetMessageId,'<networks/1847689/messages/2')"
"filterQuery": "contains(internetMessageId,'yammer.com')"

isDeliveryReceiptRequested

"filterQuery": "isDeliveryReceiptRequested eq true"
"filterQuery": "isDeliveryReceiptRequested ne false"
"filterQuery": "not(isDeliveryReceiptRequested ne false)"

isDraft

"filterQuery": "isDraft eq true"
"filterQuery": "isDraft ne false"
"filterQuery": "not(isDraft ne false)"

isRead

"filterQuery": "isRead eq true"
"filterQuery": "isRead ne false"
"filterQuery": "not(isRead ne false)"

isReadReceiptRequested

"filterQuery": "isReadReceiptRequested eq true"
"filterQuery": "isReadReceiptRequested ne false"
"filterQuery": "not(isReadReceiptRequested ne false)"

lastModifiedDateTime

"filterQuery": "lastModifiedDateTime ge 2024-06-29T08:19:33Z"
"filterQuery": "lastModifiedDateTime ge 2024-06-29"
"filterQuery": "lastModifiedDateTime gt 2024-06-29T08:19:33Z"
"filterQuery": "lastModifiedDateTime gt 2024-06-29"
"filterQuery": "lastModifiedDateTime le 2024-06-29T08:19:33Z"
"filterQuery": "lastModifiedDateTime le 2024-06-29"
"filterQuery": "lastModifiedDateTime lt 2024-06-29T08:19:33Z"
"filterQuery": "lastModifiedDateTime lt 2024-06-29"
"filterQuery": "lastModifiedDateTime ne 2024-06-29T08:19:33Z"
"filterQuery": "lastModifiedDateTime ne 2024-06-29"

receivedDateTime

"filterQuery": "receivedDateTime ge 2024-06-29T08:19:33Z"
"filterQuery": "receivedDateTime ge 2024-06-29"
"filterQuery": "receivedDateTime gt 2024-06-29T08:19:33Z"
"filterQuery": "receivedDateTime gt 2024-06-29"
"filterQuery": "receivedDateTime lt 2024-06-29T08:19:33Z"
"filterQuery": "receivedDateTime lt 2024-06-29"
"filterQuery": "receivedDateTime le 2024-06-29T08:19:33Z"
"filterQuery": "receivedDateTime le 2024-06-29"
"filterQuery": "receivedDateTime ne 2024-06-29T08:19:33Z"
"filterQuery": "receivedDateTime ne 2024-06-29"

sender/emailaddress/address

"filterQuery": "sender/emailaddress/address eq 'adele.vence@contoso.com'"
"filterQuery": "sender/emailaddress/address ne 'adele.vence@contoso.com'"
"filterQuery": "startsWith(sender/emailAddress/address,'adel')"
"filterQuery": "contains(sender/emailAddress/address,'google')"

sender/emailaddress/name

"filterQuery": "sender/emailaddress/name eq 'Microsoft Security'"
"filterQuery": "sender/emailaddress/name ne 'Microsoft Security'"
"filterQuery": "startsWith(sender/emailAddress/name,'Microsoft')"
"filterQuery": "contains(sender/emailaddress/name,'Security')"

sentDateTime

"filterQuery": "sentDateTime eq 2024-05-02T06:16:31Z"
"filterQuery": "sentDateTime eq 2024-05-02"
"filterQuery": "sentDateTime ne 2024-05-02T06:16:31Z"
"filterQuery": "sentDateTime ne 2024-05-02"
"filterQuery": "sentDateTime ge 2024-05-02T06:16:31Z"
"filterQuery": "sentDateTime ge 2024-05-02"
"filterQuery": "sentDateTime gt 2024-05-02T06:16:31Z"
"filterQuery": "sentDateTime gt 2024-05-02"
"filterQuery": "sentDateTime le 2024-05-02T06:16:31Z"
"filterQuery": "sentDateTime le 2024-05-02"
"filterQuery": "sentDateTime lt 2024-05-02T06:16:31Z"
"filterQuery": "sentDateTime lt 2024-05-02"
"filterQuery": "not(sentDateTime le 2024-05-02T06:16:31Z)"

subject

"filterQuery": "subject eq 'Secret'"
"filterQuery": "subject ne 'Secret'"
"filterQuery": "not(subject ne 'Secret')"
"filterQuery": "startswith(subject,'vacation')"
"filterQuery": "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 mail search folder is a powerful feature that allows you to create a virtual folder in user's mailbox that contains messages matching predefined search criteria.

1
Buy Me a Coffee at ko-fi.com
An error has occurred. This application may no longer respond until reloaded. Reload x