How to retrieve all mail folders in a user's mailbox using the Microsoft Graph API

Mail folders

A mail folder in a user's mailbox can be accessed using the Graph API through the following endpoint:

GET v1.0/users/{user_id}/mailFolders/{mailFolder_id}

To access some certain mail folders, you can use the well-known folder names from the table below instead of a mail folder id:

All well-known names are case-insensitive and can be use when you call the Graph API endpoint

GET v1.0/users/{user_id}/mailFolders/{well-known_folder_name}

List all mail folders

To list all mail folders in a user's mailbox, you need only two endpoints:

GET v1.0/users/{user_id}/mailFolders/{well-known_folder_name}
GET v1.0/users/{user_id}/mailFolders/{mailFolder_id}/childFolders

The both endpoints requires the Mail.Read permission. The first endpoint is used to get the root folder of the mailbox, and the second endpoint is used to get all child folders under the specified folder.

Example

Suppose you have created an Entra application and granted the permission Mail.Read to it. Now, using the Microsoft Graph .NET SDK, you can list all mail folders in signed-in user's mailbox as follows:

var options = new InteractiveBrowserCredentialOptions
{
    ClientId = "{client_id}",
    TenantId = "{tenant_id}",
    RedirectUri = new Uri("http://localhost")
};
var credential = new InteractiveBrowserCredential(options);
var client = new GraphServiceClient(credential);
var rootMailFolder = await client.Me.MailFolders["root"].GetAsync();
var indent = 0;
Console.WriteLine($"{new string('-', indent)}{rootMailFolder.DisplayName}");
await ListChildFolder(rootMailFolder.Id, client, indent + 2);

// List all child folders recursively
static async Task ListChildFolder(string id, GraphServiceClient client, int indent)
{
    var childFolders = new List<MailFolder>();
    var response = await client.Me.MailFolders[id].ChildFolders.GetAsync(rc => { rc.QueryParameters.IncludeHiddenFolders = "true"; });
    var pageIterator = PageIterator<MailFolder, MailFolderCollectionResponse>.CreatePageIterator(client, response, (folder) =>
    {
        childFolders.Add(folder);
        return true;
    });
    await pageIterator.IterateAsync();
    foreach (var childFolder in childFolders)
    {
        Console.WriteLine($"{new string('-', indent)}{childFolder.DisplayName}({childFolder.ChildFolderCount}, {childFolder.TotalItemCount})");
        await ListChildFolder(childFolder.Id, client, indent + 2);
    }
}

First, you need to get the id of the root folder of the mailbox. Then, you can list all child folders under the root folder recursively.

The result will be like this: