Move-MgUserMessage

What is Move-MgUserMessage?

Move-MgUserMessage is a Microsoft Graph PowerShell cmdlet used to move an email message from one Outlook mail folder to another within a user’s mailbox.

It works at the message level and requires the MessageId and the destination folder ID.

Why Use Move-MgUserMessage?

This cmdlet is ideal for automation scenarios such as:

• Organizing mailboxes based on rules or conditions
• Archiving old emails to specific folders
• Cleaning inboxes programmatically
• Migrating messages between folders in bulk

Unlike Outlook rules, this approach is scriptable, auditable, and scalable across users and mailboxes.

Prerequisites

Before using this cmdlet, ensure:

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

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

How to Use Move-MgUserMessage?

You must provide:

• UserId (UPN or User ID)
• MessageId
• BodyParameter containing the destination folder ID

Basic syntax:

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

The destination folder is passed using the DestinationId key inside the hashtable.

Move-MgUserMessage 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
}
                                            

Move-MgUserMessage vs Copy-MgUserMessage

Feature	Move-MgUserMessage	Copy-MgUserMessage
Action	Moves message to another folder	Copies message to another folder
Original Message	Removed from source folder	Retained in source folder
Typical Use Case	Archiving, cleanup, mailbox reorganization	Compliance, backups, duplication
Message Count Impact	Message exists in one folder only	Message exists in multiple folders
Permission Required	Mail.ReadWrite	Mail.ReadWrite
Automation Scenario	Rule-based inbox management	Auditing or parallel storage

Quick rule of thumb:

• Use Move-MgUserMessage when you want to relocate messages
• Use Copy-MgUserMessage when you want to retain the original

New-MgUserMailFolderChildFolder vs New-MgUserMailFolder

Key Point	Details
Cmdlet Name	Move-MgUserMessage
Purpose	Moves email messages between folders in a user mailbox
Required Scope	Mail.ReadWrite
Target	Outlook mailbox messages
Primary Parameters	UserId, MessageId, BodyParameter
Automation Benefit	Enables rule-based and bulk mailbox organization
Common Use Case	Archiving emails, inbox cleanup, mailbox restructuring