New-MgUserMailFolderChildFolder

What is New-MgUserMailFolderChildFolder?

New-MgUserMailFolderChildFolder is a Microsoft Graph PowerShell cmdlet used to create child (sub) mail folders inside an existing Outlook mail folder of a Microsoft 365 user’s mailbox.

It allows administrators and automation scripts to organize mailbox structures programmatically.

Why Use New-MgUserMailFolderChildFolder?

This cmdlet is especially useful for:

• Automating mailbox folder organization
• Creating standardized folder structures for users
• Migrating or restructuring mailbox data
• Bulk folder creation using scripts or CSV files

It eliminates the need for manual folder creation through Outlook or OWA.

Prerequisites

Before using this cmdlet, ensure:

• Microsoft Graph PowerShell module is installed
• You are connected to Graph with Mail.ReadWrite permission

Install-Module Microsoft.Graph -Scope CurrentUser
Connect-MgGraph -Scopes "Mail.ReadWrite"
                                        

How to Use New-MgUserMailFolderChildFolder?

The cmdlet requires:

• UserId (UPN or User ID)
• MailFolderId (parent folder ID)
• BodyParameter (hashtable containing folder properties)

Basic syntax:

New-MgUserMailFolderChildFolder -UserId  <String> -MailFolderId <String> -BodyParameter <Hashtable>

New-MgUserMailFolderChildFolder Examples

• Creating a Single Child Folder

The child folder name must be passed via -BodyParameter.

$params = @{
    displayName = "ProjectA"
}
New-MgUserMailFolderChildFolder -UserId "user@domain.com" `
-MailFolderId "AQMkADAwATM3ZmYAZC1lYwEyLTk2MTAtMAAAM_Q5fOAAA=" `
-BodyParameter $params
                                            

• Creating Multiple Child Folders

Loop through folder names and create subfolders one by one.

$folders = @("ProjectB", "ProjectC", "ProjectD")
foreach ($folder in $folders) {
    $params = @{
        displayName = $folder
    }

    New-MgUserMailFolderChildFolder -UserId "user@domain.com" `
    -MailFolderId "AQMkADAwATM3ZmYAZC1lYwEyLTk2MTAtMDACLTAwCg_Q5fOAAA=" `
    -BodyParameter $params
}
                                            

• Creating Child Folders from a CSV File

This method is ideal for bulk folder creation.

CSV File Structure

FolderName
ProjectE
ProjectF
ProjectG
                                            

PowerShell Script

$csv = Import-Csv -Path "C:\path\to\folders.csv"
foreach ($row in $csv) {
    $params = @{
        displayName = $row.FolderName
    }
    New-MgUserMailFolderChildFolder -UserId "user@domain.com" `
    -MailFolderId "AQMkADAwATM3ZmYAZC1lYwEyLTk2MTAtMDACLTAAAAM_Q5fOAAA=" `
    -BodyParameter $params
}
                                            

• Creating a Child Folder with Specific Properties

You can pass additional properties like isHidden.

$params = @{
    displayName = "Important"
    isHidden = $true
}

New-MgUserMailFolderChildFolder -UserId "user@domain.com" `
-MailFolderId "AQMkADAwATM3ZmYAZC1lYwEyLTk2MTAtMDACLsUQAFHkKlAAAM_Q5fOAAA=" `
-BodyParameter $params
                                            

New-MgUserMailFolderChildFolder vs New-MgUserMailFolder

Aspect	New-MgUserMailFolderChildFolder	New-MgUserMailFolder
Folder Level	Child (sub) folder	Root-level mail folder
Requires Parent Folder ID	✅ Yes	❌ No
Typical Usage	Creating subfolders like Projects, Years	Creating top-level folders
Automation Scenario	Structured mailbox hierarchy	Initial mailbox setup
Scope	User mailbox	User mailbox

In short:

• Use New-MgUserMailFolderChildFolder to create folders inside existing folders
• Use New-MgUserMailFolder to create top-level mail folders

Summary

Key Point	Details
Cmdlet Name	New-MgUserMailFolderChildFolder
Purpose	Creates subfolders inside an existing Outlook mail folder
Required Scope	Mail.ReadWrite
Target	User mailbox folders
Key Parameters	UserId, MailFolderId, BodyParameter
Automation Benefit	Enables scripted and bulk mailbox folder creation
Common Use Case	Mailbox organization, migrations, folder standardization