Create mailSearchFolder

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported.

Create a new mailSearchFolder in the specified user's mailbox.

Permissions

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.

POST https://graph.microsoft.com/beta/me/mailfolders/AQMkADYAAAIBDAAAAA==/childfolders
Content-type: application/json
Content-length: 159

{
  "@odata.type": "microsoft.graph.mailSearchFolder",
  "displayName": "Weekly digests",
  "includeNestedFolders": true,
  "sourceFolderIds": ["AQMkADYAAAIBDAAAAA=="],
  "filterQuery": "contains(subject, 'weekly digest')"
}

Response

The following is an example of the response.

Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('68ca8ec0-11f8-456b-a785-70d9936650d5')/mailFolders('AQMkADYAAAIBDAAAAA%3D%3D')/childFolders/$entity",
    "@odata.type": "#microsoft.graph.mailSearchFolder",
    "id": "AAMkADYfRAAAZg1yTAAA=",
    "displayName": "Weekly digests",
    "parentFolderId": "AQMkADYAAAIBDAAAAA==",
    "childFolderCount": 0,
    "unreadItemCount": 0,
    "totalItemCount": 0,
    "wellKnownName": null,
    "isSupported": true,
    "includeNestedFolders": true,
    "sourceFolderIds": [
        "AQMkADYAAAIBDAAAAA=="
    ],
    "filterQuery": "contains(subject, 'weekly digest')"
}