Mail Search folder support for Microsoft Graph APIs

Sivaprakash Saripalli

Today we’re announcing the release of mail search folder APIs to the Microsoft Graph v1.0 endpoint. A mail search folder is a virtual folder in the user’s mailbox that contains all the email items matching a specified search criterion. A Microsoft Graph app can use this feature to quickly fetch all emails that match a predefined search criterion.

We’ve had several requests for this API,  and we can’t wait to see what you’ll create. These APIs are available today on the v1.0 endpoint as /me/messages/mailfolders/ and you can try them out using Graph Explorer.

Breaking change in the beta endpoint

Along with this release, we‘re making a minor name change to one of the mailSearchFolder properties on the beta endpoint. The sourceFolderIDs property on the mailSearchFolder resource has been renamed sourceFolderIds. This change is done in accordance with Microsoft Graph naming conventions and ensures consistency between the beta and v1.0 endpoints. If your app is using the beta endpoint to access mailSearchFolder functionality, it might break due to the property rename. We recommend that you update your app to use the new property name (sourceFolderIds).

Non-breaking additive changes to v1.0

We use additive changes as a mechanism to introduce new functionality in a non-breaking way and we recommend that you code your app to handle new properties gracefully. In this case, to support mail search folder scenarios, we have added a new entity type mailSearchFolder that derives from mailFolder entity type. The following new properties are unique to the mailSearchFolder entity type: isSupported, includeNestedFolders, sourceFolderIDs, filterQuery. These properties will be available when you call the mail folders API.

Derived entities retain all the base entity properties but have their own @odata.type. In case your app is using an accept header to fetch additional OData metadata, the new returned @odata.type will be mailSearchFolder and not mailFolder for mail search folders.

These changes are available today for your app to consume. Please let us know if you have additional feedback or suggestions for new functionality. Happy coding!

Feedback usabilla icon