Get-MgUserMailFolder: How to Retrieve and Manage Mail Folders

This guide explains how to use the Get-MgUserMailFolder cmdlet in Microsoft Graph PowerShell to retrieve user mailbox folders. Learn how to list folders, fetch specific folders, and filter results with practical examples.

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"
Graph PowerShell command retrieving all mail folders for a specified user

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

Graph PowerShell command exporting mail folder details to a CSV file Graph PowerShell command displaying mail folder details in a grid view

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="
Graph PowerShell command retrieving details of a specific mail folder by its ID

Select Specific Properties

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

Get-MgUserMailFolder -UserId "user@domain.com" -Property @("Id", "DisplayName", "ChildFolderCount")
Graph PowerShell command selecting specific properties of mail folders: Id, DisplayName, and 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'"
Graph PowerShell command filtering mail folders by display name 'Inbox'

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

Error Cause Solution
"Authentication_IdentityNotFound" The specified UserId does not exist. Verify the UserId and ensure the user exists in the tenant.
"ResourceNotFound" The specified MailFolderId does not exist. Verify the MailFolderId and ensure the folder exists in the user's mailbox.
"InvalidFilter" The OData filter syntax is incorrect. Ensure the filter syntax follows OData conventions and the property names are correct.
"ErrorAccessDenied" Insufficient permissions to access the user's mailbox. Ensure the executing account has the necessary permissions to access the mailbox.

Frequently Asked Questions

  1. What is Get-MgUserMailFolder used for?
  2. 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.

  3. How can I list all folders in a user’s mailbox?
  4. Use the following command to list all folders:

    Get-MgUserMailFolder -UserId "<UserPrincipalName>"
  5. How can I retrieve a specific folder by its ID?
  6. Use the -MailFolderId parameter to retrieve a specific folder:

    Get-MgUserMailFolder -UserId "<UserPrincipalName>" -MailFolderId "<FolderId>"
  7. Can I filter folders by display name?
  8. Yes, you can filter folders after retrieval using Where-Object. Example:

    $Folders = Get-MgUserMailFolder -UserId "<UserPrincipalName>"
    $FilteredFolders = $Folders | Where-Object { $_.DisplayName -eq "Important" }
                                    
  9. How can I export mailbox folder details to a CSV file?
  10. 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

📂 Include Hidden Mail Folders When Necessary

By default, Get-MgUserMailFolder returns only visible mail folders accessible by email clients. If you're auditing or targeting folders like Sync Issues or Recoverable Items, remember to use the -IncludeHiddenFolders parameter to ensure they’re included in the output.
📁 Traverse Folder Hierarchies for Full Coverage

The cmdlet only retrieves the immediate child folders of the root by default. To access nested folders — such as subfolders under Inbox or Sent Items — you’ll need to recursively traverse each level to get a complete view of a user’s mailbox.

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.


Additional Resources:

Microsoft Graph PowerShell Module Documentation
Microsoft Graph API Documentation

Related Articles:

Using Get-MgDirectoryRole in Graph PowerShell
Using Get-MgUserLicenseDetail in Graph PowerShell
Using Find-GraphMgCommand in Graph PowerShell
Connect to Microsoft 365 Using PowerShell
How to Create Bulk Users in Office 365 Using Graph PowerShell?
Create Microsoft 365 Group Using Microsoft Graph PowerShell
Block Microsoft 365 User Using Microsoft Graph PowerShell
Assign Microsoft 365 License Using Graph PowerShell
Microsoft 365 User Management Using Graph PowerShell
Checking Group Membership in Microsoft 365
Bulk Assign Microsoft 365 License
Find Inactive Users in Microsoft 365
Using Powershell Graph Search Query
Using Powershell Graph Filter Query
Using Where-Object In Graph PowerShell
Using Expand Property In Graph PowerShell
Using Select Object In Graph PowerShell
Using -Contains Operator In Graph PowerShell
Add User to Multiple Microsoft 365 Groups Using Graph PowerShell
Get Microsoft 365 User Location Using Graph PowerShell
Import Microsoft 365 Groups from CSV File Using Graph PowerShell
Microsoft 365 Group User Import Using Graph PowerShell

© m365corner.com. All Rights Reserved. Design by HTML Codex