M365 PowerShell

Using Update-MgUserMailFolderChildFolder in Graph PowerShell

The Update-MgUserMailFolderChildFolder cmdlet in the Microsoft Graph PowerShell module allows administrators to update properties of child mail folders within a user's mailbox. This cmdlet is essential for managing and organizing mail folders effectively, especially in scenarios involving bulk updates or automation. This article provides a detailed overview, usage examples, cmdlet tips, use cases, and solutions for common errors.

Note: You need parent folder ID and child folder ID to work with this cmdlet. Use Get-MgUserMailFolder and Get-MgUserMailFolderChildFolder cmdlets to get the IDs.

Cmdlet Syntax

Update-MgUserMailFolderChildFolder -UserId <String> -MailFolderId <String> -MailFolderId1 <String> -BodyParameter <Hashtable>

-UserId: The ID of the user whose child mail folder is being updated.
-MailFolderId: The ID of the parent mail folder.
-MailFolderId1: The ID of the child mail folder.
-BodyParameter: A hashtable containing the properties to update.

Usage Examples

Example 1: Update a Single Child Mail Folder

This example updates the display name of a single child mail folder.

$params = @{
    displayName = "Updated Folder Name"
}
Update-MgUserMailFolderChildFolder -UserId "user@example.com" -MailFolderId "parentFolderId" -MailFolderId1 "childFolderId" -BodyParameter $params

Example 2: Update Multiple Child Mail Folders

This example updates multiple child mail folders by iterating over a collection of folders.

$folders = @(
    @{
        UserId = "user@example.com"
        ParentFolderId = "parentFolderId"
        ChildFolderId = "childFolderId1"
        Params = @{
            displayName = "Updated Folder Name 1"
        }
    }
    @{
        UserId = "user@example.com"
        ParentFolderId = "parentFolderId"
        ChildFolderId = "childFolderId2"
        Params = @{
            displayName = "Updated Folder Name 2"
        }
    }
)

foreach ($folder in $folders) {
    Update-MgUserMailFolderChildFolder -UserId $folder.UserId -MailFolderId $folder.ParentFolderId -MailFolderId1 $folder.ChildFolderId -BodyParameter $folder.Params
}

Example 3: Update Child Mail Folders from a CSV File

In this example, updates are made to child mail folders based on data from a CSV file. The CSV should contain columns: UserId, ParentFolderId, ChildFolderId, and DisplayName.

PowerShell Script:

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

foreach ($folder in $folders) {
    $params = @{
        displayName = $folder.DisplayName
    }
    Update-MgUserMailFolderChildFolder -UserId $folder.UserId -MailFolderId $folder.ParentFolderId -MailFolderId1 $folder.ChildFolderId -BodyParameter $params
}

Cmdlet Tips

Always verify the UserId, MailFolderId, and MailFolderId1 to ensure they correspond to the correct user and folder.
Use Get-MgUserMailFolder to retrieve parent folder IDs and Get-MgUserMailFolderChildFolder to retrieve child folder IDs if they are not known.
When performing bulk updates, ensure the data is accurate to avoid unintended changes.

Use Cases

Renaming User Mail Folders for Better Organization:

Scenario: Over time, users might create several mail folders that are poorly named or difficult to navigate. Administrators may need to help users rename their mail folders to improve organization and searchability.
Implementation: Use Update-MgUserMailFolderChildFolder to update the display names of mail folders for better clarity, such as renaming generic folders like “Work” to something more descriptive like “Project A - Work.”
Benefit: Helps users manage their inboxes more effectively by making mail folders easier to navigate and search, improving overall productivity.

Adjusting Folder Permissions for Shared Mailboxes:

Scenario: In organizations where shared mailboxes are used, folder permissions may need to be updated to grant or revoke access for certain users based on changes in roles or responsibilities.
Implementation: Use Update-MgUserMailFolderChildFolder to update folder-level permissions, ensuring that only authorized individuals have access to sensitive or important email content within shared mailboxes.
Benefit: Improves security by enforcing appropriate access controls and helps manage collaboration on shared mailboxes more effectively.

Updating Folder Properties to Reflect Project Status:

Scenario: Some mail folders are project-specific, and once the project status changes (e.g., completed, on-hold), folder properties such as display names or categories need to be updated accordingly.
Implementation: Use Update-MgUserMailFolderChildFolder to update folder names, descriptions, or other properties to reflect the current status of a project. For example, renaming a folder to include “[Completed]” or “[In Progress]” in its title.
Benefit: Keeps project-related communications well-organized and clearly indicates the status of each project within the mailbox, reducing confusion for users.

Automating Folder Structure Updates Based on User Roles:

Scenario: As users take on new roles or responsibilities, their email folders may need to be restructured or renamed to reflect their updated work scope.
Implementation: Use Update-MgUserMailFolderChildFolder to automate the process of updating mail folder structures based on user roles. For example, when a user is promoted to a manager role, folders could be updated to reflect their new project or team-related responsibilities.
Benefit: Automates a critical part of user role transitions, ensuring that email folder structures evolve as users' responsibilities change, making it easier for them to manage relevant communications.

Possible Errors and Solutions

Error: InvalidAuthenticationToken

Cause: The authentication token provided is invalid or expired.

Solution: Re-authenticate using Connect-MgGraph to obtain a new token.

Connect-MgGraph -Scopes "Mail.ReadWrite"

Error: ResourceNotFound

Cause: The specified MailFolderId or MailFolderId1 does not exist.

Solution: Verify the folder IDs using the Get-MgUserMailFolder cmdlet (and Get-MgUserMailFolderChildFolder cmdlet) to ensure they are correct.

Get-MgUserMailFolder -UserId "user@example.com" -MailFolderId "parentFolderId"
Get-MgUserMailFolderChildFolder -UserId "user@domain.com" -MailFolderId "inbox"

Error: InsufficientPermissions

Cause: The authenticated user does not have the required permissions.

Solution: Ensure the necessary permissions are granted to the application or user. The required permissions are Mail.ReadWrite.

Conclusion

The Update-MgUserMailFolderChildFolder cmdlet is a powerful tool for managing child mail folders within a user's mailbox. By understanding its syntax, usage examples, and potential errors, administrators can effectively utilize this cmdlet for various organizational tasks. Whether updating a single folder, multiple folders, or automating updates via CSV, this cmdlet enhances the efficiency and accuracy of mailbox management.

Additional Resources:

Microsoft Graph PowerShell Module Documentation
Microsoft Graph API Documentation

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