One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.
Permission type
Permissions (from least to most privileged)
Delegated (work or school account)
Mail.ReadWrite
Delegated (personal Microsoft account)
Mail.ReadWrite
Application
Mail.ReadWrite
HTTP request
POST /me/mailFolders/{id}/childFolders
POST /users/{id | userPrincipalName}/mailFolders/{id}/childFolders
Specify the parent folder in the query URL as a folder ID, or a well-known folder name. For a list of supported well-known folder names, see mailFolder resource type.
Request headers
Header
Value
Authorization
Bearer {token}. Required.
Content-Type
application/json. Required.
Request body
In the request body, provide a JSON object with the following parameters.
Parameter
Type
Description
@odata.type
String
The type of folder to be created. Set to "microsoft.graph.mailSearchFolder".
displayName
String
The display name of the new folder.
includeNestedFolders
Boolean
Indicates how the mailbox folder hierarchy should be traversed in the search. true means that a deep search should be done to include child folders in the hierarchy of each folder explicitly specified in sourceFolderIds. false means a shallow search of only each of the folders explicitly specified in sourceFolderIds.
sourceFolderIds
String collection
The mailbox folders that should be mined.
filterQuery
String
The OData query to filter the messages.
Response
If successful, this method returns a 201 Created response code and a mailSearchFolder object in the response body.
Example
Request
The following is an example of the request - it creates a search folder of messages that contain the string "weekly digest" in the subject. The search folder is under the same folder on which the specified filter query applies.
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new MailFolder();
$requestBody->set@odatatype('microsoft.graph.mailSearchFolder');
$requestBody->setDisplayName('Weekly digests');
$additionalData = [
'includeNestedFolders' => true,
'sourceFolderIds' => ['AQMkADYAAAIBDAAAAA==', ],
'filterQuery' => 'contains(subject, \'weekly digest\')',
];
$requestBody->setAdditionalData($additionalData);
$requestResult = $graphServiceClient->me()->mailFoldersById('mailFolder-id')->childFolders()->post($requestBody);