How to Use Get-MgUserMailFolder to Fetch User Mail Folders?

Managing mail folders is a common task for Microsoft 365 administrators. Whether you’re auditing user mailboxes, retrieving folder structure, or building automation around mailbox cleanup, the Get-MgUserMailFolder cmdlet comes in handy.

In this guide, we’ll walk through what this cmdlet does, why it’s useful, how to use it effectively, and provide real-world examples to help you get started.

What is Get-MgUserMailFolder?

Get-MgUserMailFolder is a Microsoft Graph PowerShell cmdlet used to retrieve the mail folders of a user in Microsoft 365. You can fetch all folders, a specific folder, child folders, or even apply filters to fetch folders based on properties like display name or folder ID.

This cmdlet is part of the Microsoft.Graph.Users.Mail module and requires proper permissions to access a user's mailbox.

Why Use Get-MgUserMailFolder?

Here are some reasons administrators and developers rely on Get-MgUserMailFolder:

• View complete mailbox folder hierarchy
• Troubleshoot mailbox sync issues
• Identify and report on custom folders
• Assist with migration or cleanup tasks
• Automate mailbox audits for security or compliance

Cmdlet Syntax

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

Parameters:

• UserId: Required. The UserPrincipalName (UPN) or User ID (GUID) of the mailbox owner.
• MailFolderId: Optional. The unique ID of the folder you want to fetch.
• Property: Optional. Used to retrieve only specific properties.
• Filter: Optional. Used to filter folders by a condition (like folder name).

Usage Examples

Get All Mail Folders

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

This command retrieves all mail folders from the user's mailbox, including default and custom folders.

Get a Single Mail Folder by ID

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

If you already have the folder ID (for example, from a previous query), you can retrieve the full folder details using this method.

Select Specific Properties

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

Limit the output to only show selected properties — this makes your scripts cleaner and faster when processing large mailboxes.

Filter Folders by Display Name

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

Want to find only the "Inbox"? Use the -Filter parameter to zero in on specific folders by name.

Frequently Asked Questions

What permissions do I need to run this cmdlet?

You’ll need Mail.Read or Mail.ReadWrite delegated permissions, or Mail.ReadBasic.All application permissions when using app-only access.

Can I retrieve child folders?

Yes. Each folder object contains a ChildFolderCount and ChildFolders relationship, which you can explore using the -ExpandProperty parameter.

What if the user’s mailbox is very large?

You may consider paginating the results or using Select-Object to limit the returned fields for performance.

Use Cases

• Mailbox Folder Auditing: Ensure standard folders exist and detect unauthorized custom folders.
• Compliance Reporting: Generate folder structure reports for VIP or executive mailboxes.
• Automation: Combine this with New-MgUserMailFolder or Move-MgUserMessage to automate folder management.

Conclusion

Get-MgUserMailFolder is a versatile tool for managing Microsoft 365 mailboxes. Whether you're performing audits, building automation workflows, or simply exploring user folder structures, this cmdlet makes it easy.

By mastering the examples above, you’ll be ready to use Get-MgUserMailFolder in real-world scenarios — with clarity, control, and confidence.