M365 PowerShell

Using Move-MgUserMessage in Graph PowerShell

Efficient email management often requires moving messages between folders within a user's mailbox. The Move-MgUserMessage cmdlet in Microsoft Graph PowerShell enables administrators to move messages seamlessly. This article covers the cmdlet's syntax, usage examples, tips, use cases, possible errors, and their solutions.

Cmdlet Syntax

Move-MgUserMessage -UserId <String> -MessageId <String> -BodyParameter <Hashtable>

UserId: The unique identifier of the user. It can be the user's UPN or User ID.
MessageId: The unique identifier of the message to be moved.
BodyParameter: A hashtable containing the destination folder details.

Note: To move messages between folders, you need the folder ID, which can be got using Get-MgUserMailFolder cmdlet.

Usage Examples

Move a Single Message to a Specific Folder

$params = @{
    DestinationId = "AQMkAGI2TAAA="
}
Move-MgUserMessage -UserId "user@domain.com" -MessageId "AAMkADhZD3KZAAA=" -BodyParameter $params

Move Multiple Messages to a Specific Folder

$messages = @("AAMkADhZD3KZAAA=", "AAMkADhZD3KZAAQ=")
$destination = @{
    DestinationId = "AQMkAGI2TAAA="
}
foreach ($messageId in $messages) {
    Move-MgUserMessage -UserId "user@domain.com" -MessageId $messageId -BodyParameter $destination
}

Move Messages Based on a Condition

$oldMessages = Get-MgUserMessage -UserId "user@domain.com" -Filter "receivedDateTime lt 2023-01-01"
$destination = @{
    DestinationId = "AQMkAGI2TAAA="
}
foreach ($message in $oldMessages) {
    Move-MgUserMessage -UserId "user@domain.com" -MessageId $message.Id -BodyParameter $destination
}

Move All Messages from One Folder to Another

$folderMessages = Get-MgUserMessage -UserId "user@domain.com" -MailFolderId "AQMkADhZD3KZAAAA=" -All
$destination = @{
    DestinationId = "AQMkAGI2TAAA="
}
foreach ($message in $folderMessages) {
    Move-MgUserMessage -UserId "user@domain.com" -MessageId $message.Id -BodyParameter $destination
}

Cmdlet Tips

Use UserPrincipalName: You can use the user's email address as the UserId.
Verify Destination Folder ID: Ensure the DestinationId is correct to avoid errors.
Automate Message Organization: Use scripts to automate the organization of emails based on specific conditions.

Use Cases

Mailbox Organization: Automatically move messages to designated folders based on specific criteria.
Project Management: Move project-related emails to project-specific folders.
Email Cleanup: Regularly move older emails to archive folders to keep the inbox tidy.

Possible Errors & Solutions

Error: "Authentication_IdentityNotFound"

Cause: The specified UserId does not exist.

Solution: Verify the UserId and ensure the user exists in the tenant.

Error: "ResourceNotFound"

Cause: The specified MessageId or DestinationId does not exist.

Solution: Verify the MessageId and DestinationId and ensure they exist in the user's mailbox.

Error: "InvalidRequest"

Cause: Invalid parameters passed to the cmdlet.

Solution: Ensure the BodyParameter is correctly formatted and contains valid keys.

Error: "ErrorAccessDenied"

Cause: Insufficient permissions to move the message.

Solution: Ensure the executing account has the necessary permissions to move messages in the specified mailbox.

Frequently Asked Questions

1. What is Move-MgUserMessage used for?

Move-MgUserMessage is a Microsoft Graph PowerShell cmdlet used to move email messages from one folder to another in a user’s mailbox.

2. How can I move a single email message to another folder?

Use the following command to move a specific message:

Move-MgUserMessage -UserId "<UserPrincipalName>" -MessageId "<MessageId>" -DestinationId "<DestinationFolderId>"

3. Can I move multiple messages to another folder?

Yes, retrieve messages using a query or filter and then move them in a loop. Example:

$Messages = Get-MgUserMessage -UserId "<UserPrincipalName>" -Filter "isRead eq false"
foreach ($Message in $Messages) {
    Move-MgUserMessage -UserId "<UserPrincipalName>" -MessageId $Message.Id -DestinationId "<DestinationFolderId>"
}

4. What permissions are required to use Move-MgUserMessage?

You need the Mail.ReadWrite permission in Microsoft Graph PowerShell. Ensure these permissions are granted in Azure AD.

Conclusion

The Move-MgUserMessage cmdlet is a powerful tool for organizing and managing emails within Microsoft 365 mailboxes. By understanding its syntax, usage examples, and potential errors, IT administrators can efficiently move messages, ensuring mailboxes remain organized and manageable.

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