List childFolders

Namespace: microsoft.graph

Get the folder collection under the specified folder. You can use the .../me/mailFolders shortcut to get the top-level folder collection and navigate to another folder.

By default, this operation does not return hidden folders. Use a query parameter includeHiddenFolders to include them in the response.

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.ReadBasic, Mail.Read, Mail.ReadWrite
Delegated (personal Microsoft account) Mail.ReadBasic, Mail.Read, Mail.ReadWrite
Application Mail.ReadBasic.All, Mail.Read, Mail.ReadWrite

HTTP request

To get all the child folders under the specified folder, excluding those that are hidden:

GET /me/mailFolders/{id}/childFolders
GET /users/{id | userPrincipalName}/mailFolders/{id}/childFolders

To include hidden child folders in the response:

GET /me/mailFolders/{id}/childFolders?includeHiddenFolders=true
GET /users/{id | userPrincipalName}/mailFolders/{id}/childFolders?includeHiddenFolders=true

Optional query parameters

To return a list of all childFolders including those that are hidden (their isHidden property is true), in the request URL, specify the includeHiddenFolders query parameter as true, as shown in the HTTP request section.

This method supports the OData Query Parameters to help customize the response.

Request headers

Name Type Description
Authorization string Bearer {token}. Required.

Request body

Do not supply a request body for this method.

Response

If successful, this method returns a 200 OK response code and collection of mailFolder objects in the response body.

Example

Example 1: List mail folders

The following is an example of the request.

Request

Here is an example of the request.

GET https://graph.microsoft.com/v1.0/me/mailFolders/{id}/childFolders
Response

Here is an example of the response. Note: The response object shown here might be shortened for readability.

HTTP/1.1 200 OK
Content-type: application/json
Content-length: 232

{
  "value": [
    {
      "id": "id-value",
      "displayName": "displayName-value",
      "parentFolderId": "parentFolderId-value",
      "childFolderCount": 99,
      "unreadItemCount": 99,
      "totalItemCount": 99,
      "isHidden": false
    }
  ]
}

Example 2: Include hidden child folders under a specified mail folder

The next example uses the includeHiddenFolders query parameter to get a list of child folders under a specified mail folder including hidden mail folders. The response includes the "Clutters" folder that has the isHidden set to true.

Request

Here is an example of the request.

GET https://graph.microsoft.com/v1.0/me/mailFolders/{id}/childFolders?includeHiddenFolders=true
Response

Here is an example of the response. Note: The response object shown here might be shortened for readability.

HTTP/1.1 200 OK
Content-type: application/json
Content-length: 232

{
  "value": [
    {
      "id": "AAMkAGVmMDEzA",
      "displayName": "Internal Screens",
      "parentFolderId": "AAMkAGVmMDEzM",
      "childFolderCount": 0,
      "unreadItemCount": 2,
      "totalItemCount": 2,
      "isHidden": false
    },
    {
      "id": "AAMkAGVmMDEzB",
      "displayName": "Clutters",
      "parentFolderId": "AAMkAGVmMDEzM",
      "childFolderCount": 0,
      "unreadItemCount": 5,
      "totalItemCount": 5,
      "isHidden": true
    }
  ]
}