Get-MgUserMailFolder: How to Retrieve and Manage Mail Folders

Efficient mailbox management often requires retrieving and managing mail folders within user mailboxes. The Get-MgUserMailFolder cmdlet in Microsoft Graph PowerShell enables administrators to retrieve mail folders with ease. This article covers the cmdlet's syntax, usage examples, tips, use cases, possible errors, and their solutions.

Cmdlet Syntax

Get-MgUserMailFolder -UserId <String> [-MailFolderId <String>] [-Property <String[]>] [-Filter <String>]

• UserId: The unique identifier of the user. It can be the user's UPN or User ID.
• MailFolderId: (Optional) The unique identifier of the mail folder.
• Property: (Optional) Specifies which properties to include in the response.
• Filter: (Optional) OData filter to limit the results.

Usage Examples

Get All Mail Folders

Pass the User ID or UserPrincipalName to -UserId parameter.

Get-MgUserMailFolder -UserId "user@domain.com"

Best way to work with Folder IDs would be to export the details.

Get a Single Mail Folder by ID

To get the details of a single mail folder, you should pass the MailFolderId along with the UserId.

Get-MgUserMailFolder -UserId "user@domain.com" -MailFolderId "AQMkAGI2TAAA="

Select Specific Properties

Use the -Property parameter to select specific mail folder properties.

Get-MgUserMailFolder -UserId "user@domain.com" -Property @("Id", "DisplayName", "ChildFolderCount")

Filter Folders by Display Name

You can also use -Filter while working with the mail folders being retrieved.

Get-MgUserMailFolder -UserId "user@domain.com" -Filter "displayName eq 'Inbox'"

Find Mail Folders with High Item Count

Use this example to identify folders that may need cleanup, archiving, or retention review.

    Connect-MgGraph -Scopes "Mail.Read"

    $UserId = "user@domain.com"

    Get-MgUserMailFolder -UserId $UserId -All -Property "id,displayName,totalItemCount,unreadItemCount,childFolderCount" |
    Select-Object DisplayName, TotalItemCount, UnreadItemCount, ChildFolderCount, Id |
    Sort-Object TotalItemCount -Descending |
    Format-Table -AutoSize

What this script does

This script retrieves the user’s mail folders and sorts them by TotalItemCount in descending order. It helps quickly identify folders with large volumes of emails.

Why this example is useful

This is helpful when investigating mailbox bloat, user complaints about Outlook performance, or folders that may require cleanup before migration.

Export Mail Folder Report to CSV

Use this example to create a mailbox folder inventory report for auditing or documentation.

    Connect-MgGraph -Scopes "Mail.Read"

    $UserId = "user@domain.com"
    $ExportPath = "C:\Reports\MailFolderReport.csv"

    $Folders = Get-MgUserMailFolder -UserId $UserId -All -Property "id,displayName,totalItemCount,unreadItemCount,childFolderCount"

    $Folders |
    Select-Object DisplayName, TotalItemCount, UnreadItemCount, ChildFolderCount, Id |
    Export-Csv -Path $ExportPath -NoTypeInformation

    Write-Host "Mail folder report exported to $ExportPath"

What this script does

This script retrieves the user’s mail folders and exports folder details such as folder name, total item count, unread item count, child folder count, and folder ID to a CSV file.

Why this example is useful

This is useful for mailbox audits, migration planning, and documenting folder structure before performing cleanup or automation tasks.

Cmdlet Tips

• Use UserPrincipalName: You can use the user's email address as the UserId.
• Combine Properties: Use the -Property parameter to retrieve only the necessary properties, improving performance.
• Utilize Filters: Use the -Filter parameter to narrow down results based on specific criteria.
• Use export-csv and out-gridview: Utilize these cmdlets to work with folder IDs easily.

Use Cases

• Mailbox Auditing: Retrieve all mail folders to audit mailbox structure and contents.
• Folder Management: Identify and manage specific folders within a user's mailbox.
• Automated Reports: Generate reports on mailbox folder structures and usage.

Possible Errors & Solutions

Frequently Asked Questions

1. What is Get-MgUserMailFolder used for?

Get-MgUserMailFolder is a Microsoft Graph PowerShell cmdlet used to retrieve folders from a user’s mailbox, including default folders like Inbox, Sent Items, and custom folders.

2. How can I list all folders in a user’s mailbox?

Use the following command to list all folders:

Get-MgUserMailFolder -UserId "<UserPrincipalName>"

3. How can I retrieve a specific folder by its ID?

Use the -MailFolderId parameter to retrieve a specific folder:

Get-MgUserMailFolder -UserId "<UserPrincipalName>" -MailFolderId "<FolderId>"

4. Can I filter folders by display name?

Yes, you can filter folders after retrieval using Where-Object. Example:

$Folders = Get-MgUserMailFolder -UserId "<UserPrincipalName>"
$FilteredFolders = $Folders | Where-Object { $_.DisplayName -eq "Important" }
                        

5. How can I export mailbox folder details to a CSV file?

Use this script to export folder details:

$Folders = Get-MgUserMailFolder -UserId "<UserPrincipalName>"
$Folders | Select-Object DisplayName, ParentFolderId, TotalItemCount | Export-Csv -Path "C:\Path\To\MailboxFolders.csv" -NoTypeInformation

Conclusion

The Get-MgUserMailFolder cmdlet is a versatile tool for managing mail folders within Microsoft 365 mailboxes. By understanding its syntax, usage examples, and potential errors, IT administrators can efficiently retrieve and manage mail folders, streamlining mailbox management tasks and enhancing productivity.

If You Prefer the Graph API Way

You can retrieve and filter mail folders using the Microsoft Graph API's /users/{id}/mailFolders endpoint. The following examples demonstrate how to list all folders, fetch a specific folder by ID, select key properties, and apply filters like display name — all directly via Invoke-MgGraphRequest.

1. Get All Mail Folders for a User

$userId = "user@domain.com"
$uri = "https://graph.microsoft.com/v1.0/users/$userId/mailFolders"

$response = Invoke-MgGraphRequest -Method GET -Uri $uri

foreach ($folder in $response.value) {
Write-Output "Folder ID      : $($folder.id)"
Write-Output "Display Name   : $($folder.displayName)"
Write-Output "Child Folders  : $($folder.childFolderCount)"
Write-Output "Total Items    : $($folder.totalItemCount)"
Write-Output "`n"
}
                        

✅ Equivalent to: Get-MgUserMailFolder -UserId "user@domain.com"

2. Get a Single Mail Folder by Folder ID

$userId = "user@domain.com"
$mailFolderId = "AQMkAGI2TAAA="  # Replace with actual folder ID

$uri = "https://graph.microsoft.com/v1.0/users/$userId/mailFolders/$mailFolderId"

$response = Invoke-MgGraphRequest -Method GET -Uri $uri

Write-Output "Folder ID      : $($response.id)"
Write-Output "Display Name   : $($response.displayName)"
Write-Output "Is Hidden      : $($response.isHidden)"
Write-Output "Total Items    : $($response.totalItemCount)"
                        

✅ Equivalent to: Get-MgUserMailFolder -UserId "user@domain.com" -MailFolderId "AQMkAGI2TAAA="

3. Select Specific Properties (Id, DisplayName, ChildFolderCount)

$userId = "user@domain.com"
$uri = "https://graph.microsoft.com/v1.0/users/$userId/mailFolders?$select=id,displayName,childFolderCount"

$response = Invoke-MgGraphRequest -Method GET -Uri $uri

foreach ($folder in $response.value) {
Write-Output "ID             : $($folder.id)"
Write-Output "Display Name   : $($folder.displayName)"
Write-Output "Child Folders  : $($folder.childFolderCount)"
Write-Output "`n"
}
                        

✅ Equivalent to:
Get-MgUserMailFolder -UserId "user@domain.com" -Property @("Id", "DisplayName", "ChildFolderCount")

4. Filter Folders by Display Name (e.g., Inbox)

$userId = "user@domain.com"
$filter = "displayName eq 'Inbox'"
$uri = "https://graph.microsoft.com/v1.0/users/$userId/mailFolders?$filter=$filter"

$response = Invoke-MgGraphRequest -Method GET -Uri $uri

foreach ($folder in $response.value) {
Write-Output "Folder ID      : $($folder.id)"
Write-Output "Display Name   : $($folder.displayName)"
}
                        

✅ Equivalent to:
Get-MgUserMailFolder -UserId "user@domain.com" -Filter "displayName eq 'Inbox'"

Required Permissions

• Delegated: Mail.Read, Mail.ReadWrite
• Application: Mail.Read, Mail.ReadWrite

Graph API Documentation

• 👉 GET /users/{id}/mailFolders
• 👉 GET /users/{id}/mailFolders/{id}

Additional Resources:

Related Articles: