Using Move-MgUserMailFolder in Graph PowerShell

The Move-MgUserMailFolder cmdlet is part of the Microsoft Graph PowerShell module enabling administrators to move a mail folder from one folder to another within a user’s mailbox. This is particularly useful when organizing user mailboxes or performing automated cleanup tasks for large environments.

In this article, we'll explore the cmdlet's syntax, provide detailed usage examples, offer cmdlet tips, cover possible errors and solutions, discuss real-world use cases, and wrap up with a conclusion.

Cmdlet Syntax

Move-MgUserMailFolder -MailFolderId <String> -UserId <String> -BodyParameter <Hashtable>

The parameters:

• MailFolderId: The ID of the folder you wish to move.
• UserId: The unique identifier (or UPN) of the user whose mail folder is being moved.
• BodyParameter: A hashtable that specifies the parent folder to move the folder into. The ParentFolderId must be provided in the hashtable.

Usage Examples

Example 1: Move a User's Subfolder to Another Folder

$Body = @{
    ParentFolderId = "AAMkAGI2TAAk3y..."  # Destination folder ID
}
Move-MgUserMailFolder -MailFolderId "AQMkADAwATM0MAIt..." -UserId "jdoe@company.com" -BodyParameter $Body

In this example, a folder identified by MailFolderId is moved to the folder specified by ParentFolderId. This is a straightforward operation often used when reorganizing user mailboxes.

Example 2: Move a Folder Using UserId

    $Body = @{
    ParentFolderId = "AQMkADAwATM0M..."  # Parent folder ID
    }
    Move-MgUserMailFolder -MailFolderId "AAMkADhNWj..." -UserId "02627e97-4100-4c3e-9690-5740a44f4e24" -BodyParameter $Body

Instead of using the user's UserPrincipalName, this example shows how you can use the user’s ID to move a folder, offering more flexibility when working with mailboxes.

Example 3: Move All Subfolders That Match a Specific Filter

# Retrieve subfolders using a filter and move them
$folders = Get-MgUserMailFolder -UserId "user@domain.com" -Filter "DisplayName eq 'Projects'"

foreach ($folder in $folders) {
    $Body = @{
        ParentFolderId = "AQMkAGY3..."  # Parent folder ID
    }
    Move-MgUserMailFolder -MailFolderId $folder.Id -UserId "user@domain.com" -BodyParameter $Body
}

In this example, we filter for folders with the name "Projects" and move them to a new parent folder. This automation technique is useful for organizing project-specific mail folders.

Cmdlet Tips

• Always Use Valid Folder IDs: Ensure that both MailFolderId and ParentFolderId are valid. Using incorrect or outdated IDs will result in failure.
• Test with Non-Critical Folders First: Before automating folder moves on a large scale, test with smaller or less critical folders to ensure everything is set up correctly.
• Leverage Filtering for Automation: Combining Get-MgUserMailFolder with filtering options (e.g., -Filter parameter) allows for dynamic folder management based on criteria such as folder names or specific properties.

Possible Errors and Solutions

Error	Cause	Solution
InvalidAuthenticationToken	Authentication token is missing or expired.	Ensure that the Graph PowerShell module is authenticated with valid credentials before running the cmdlet. Use Connect-MgGraph to re-authenticate if necessary.
ErrorInvalidIdMalformed	One of the IDs (MailFolderId or ParentFolderId) is invalid or malformed.	Double-check the folder IDs provided in the command. Retrieve valid IDs using Get-MgUserMailFolder.
Request_BadRequest	The request is malformed, likely due to an incorrect BodyParameter format.	Ensure that the BodyParameter adheres to the required format and only valid keys (such as ParentFolderId) are used. Follow the Microsoft documentation for reference.
ErrorItemNotFound	The folder or user specified does not exist.	Ensure that the MailFolderId and UserId provided are correct and that the user has access to the folder you're trying to move.
ErrorAccessDenied	Insufficient permissions to move the folder.	Ensure the necessary permissions (like Mail.ReadWrite) are granted to your app registration or delegated permissions if using delegated access.

Use Cases

• Mailbox Cleanup Automation: Automating the process of moving subfolders based on criteria (like project or department names) helps IT teams keep mailboxes organized and clutter-free. For example, folders related to old projects can be moved to an archive folder.
• Post-Migration Folder Organization: After migrating users from one mail system to another, folders may not be properly organized. Use this cmdlet to streamline and re-structure mail folders based on predefined organizational structures.
• Mailbox Restructuring for Role Changes: When an employee changes roles or departments, their mailbox may need to be reorganized to reflect their new responsibilities. For instance, project-specific mail folders can be moved under a new department folder.

Conclusion

The Move-MgUserMailFolder cmdlet is a powerful tool for automating mailbox folder management in Microsoft 365. Whether it’s cleaning up old project folders or reorganizing a user’s mailbox after a role change, this cmdlet provides flexibility for administrators. However, it’s important to follow the correct conventions for the BodyParameter and test thoroughly to avoid common errors like invalid folder IDs or permission issues.

By automating folder moves, IT admins can save significant time while maintaining an organized mailbox structure across the organization.