How to Use New-MgUserMailFolder to Create User Mail Folders?

Organizing mailbox folders is essential for maintaining a clutter-free email experience—especially in large enterprises where communication is nonstop. Whether you're onboarding users, preparing shared mailbox structures, or building automated routines, the New-MgUserMailFolder cmdlet can be your best friend.

This blog will show you how to use New-MgUserMailFolder to create mail folders in a Microsoft 365 user's mailbox using PowerShell and Microsoft Graph.

What is New-MgUserMailFolder?

New-MgUserMailFolder is a Microsoft Graph PowerShell cmdlet that allows administrators to create new mail folders in a user's mailbox.

You can create folders in the root of the mailbox or nest them inside existing folders. It’s especially useful when setting up folder structures programmatically for multiple users.

Why Use New-MgUserMailFolder?

Here’s why this cmdlet is a game-changer for admins:

• Organize mailboxes efficiently
• Automate folder creation for onboarding or migrations
• Prepare structured mailboxes for shared or group accounts
• Integrate folder creation into scripts and workflows

Cmdlet Syntax

New-MgUserMailFolder -UserId <String> -BodyParameter <Hashtable>

Parameters:

• UserId: The UPN or GUID of the mailbox user.
• BodyParameter: A hashtable containing folder properties such as displayName and optionally parentFolderId.

Usage Examples

Create a New Folder in the Root Mailbox

$params = @{
    displayName = "Project Documents"
}
New-MgUserMailFolder -UserId "user@domain.com" -BodyParameter $params
                                        

This creates a basic plain-text message. You can send it using Send-MgUserMessage.

Create a New Folder within an Existing Folder

$params = @{
    displayName = "Invoices"
    parentFolderId = "AQMkAGI2TAAA="
}
New-MgUserMailFolder -UserId "user@domain.com" -BodyParameter $params
                                        

This creates a folder named "Invoices" nested inside an existing folder with ID AQMkAGI2TAAA=.

Create Multiple Folders Programmatically

$folders = @("HR", "Finance", "IT")
foreach ($folder in $folders) {
    $params = @{
        displayName = $folder
    }
    New-MgUserMailFolder -UserId "user@domain.com" -BodyParameter $params
}
                                        

Perfect for setting up default folders for new users or departmental mailboxes.

Import Folders from a CSV File

Sample CSV content:

FolderName,ParentFolderId
Team Meetings,AQMkAGI2TAAA=
Finance,BQMkBGI3TBBB=
IT,CQNkCGI4TCCC=
                                        

PowerShell Script:

$csvPath = "C:\Path\To\Folders.csv"
$folders = Import-Csv -Path $csvPath

foreach ($folder in $folders) {
    $params = @{
        displayName = $folder.FolderName
        parentFolderId = $folder.ParentFolderId
    }
    New-MgUserMailFolder -UserId "user@domain.com" -BodyParameter $params
}
                                            
                                        

This lets you bulk-create folders using a simple spreadsheet—ideal for large-scale mailbox setups.

Verifying Newly Created Folders

Get-MgUserMailFolder -UserId "user@domain.com" | Out-GridView

Use this to visually inspect the newly created folders and confirm their structure.

Frequently Asked Questions

• Can I create subfolders inside the Inbox?
  Yes! Just use the Inbox folder's ID as the parentFolderId.
• What happens if a folder with the same name already exists?
  An error is thrown. You’ll need to check for existing folders first or use unique names.
• Can I create folders for shared mailboxes?
  Yes—just pass the shared mailbox UPN to the -UserId parameter.
• Do I need special permissions?
  Yes. You'll need Mail.ReadWrite permission delegated or app-only, depending on your auth model.

Use Cases

• New User Onboarding: Automatically create folders like "HR", "Finance", or "Policies".
• Shared Mailboxes: Structure mail folders by topic or department.
• Compliance & Organization: Help users stay compliant by organizing mail effectively.
• Workflow Integration: Combine with New-MgUserMessage or Move-MgUserMessage to build full automation flows.

Conclusion

The New-MgUserMailFolder cmdlet gives administrators a simple, scalable way to create and manage folders inside Microsoft 365 mailboxes. From one-off folder creation to bulk scripts using CSVs, it's a tool that belongs in every PowerShell-savvy admin's toolkit.

Take it a step further by combining it with other cmdlets for a truly automated email management solution.