Copy-MgUserMessage

What is Copy-MgUserMessage?

Copy-MgUserMessage is a Microsoft Graph PowerShell cmdlet used to copy an email message from one Outlook mail folder to another within a user’s mailbox without removing the original message.

The source message remains intact, making this cmdlet ideal for duplication and retention scenarios.

Why Use Copy-MgUserMessage?

This cmdlet is commonly used when:

• Emails must be retained in the original folder
• Messages need to be duplicated for compliance or auditing
• Important emails must exist in multiple folders
• Automating mailbox backups or parallel storage

Unlike Move-MgUserMessage, this cmdlet does not alter the original folder structure.

Prerequisites

Before running 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 Copy-MgUserMessage?

You must specify:

• UserId (UPN or User ID)
• MessageId
• DestinationId (target mail folder ID)

Basic syntax:

Copy-MgUserMessage -UserId  <String> -MessageId  <String> -DestinationId <String>

Copy-MgUserMessage Examples

• Example 1: Copy a Single Message

This example copies a single email message with the specified MessageId from the user's mailbox to the destination folder identified by DestinationId.

Copy-MgUserMessage -UserId "user@domain.com" -MessageId "AAMkAG..." -DestinationId "AQMkAG..."

• Example 2: Copy Multiple Messages

This example copies multiple messages by iterating through an array of MessageId values and copying each one to the specified destination folder.

$messageIds = @("AAMkAG...", "AAMkBG...")
foreach ($id in $messageIds) {
    Copy-MgUserMessage -UserId "user@domain.com" -MessageId $id -DestinationId "AQMkAG..."
}
                                            

• Example 3: Copy Messages Based on Filter Condition

This example retrieves messages with a specific subject using the Get-MgUserMessage cmdlet and then copies those messages to the desired folder.

$messages = Get-MgUserMessage -UserId "user@domain.com" -Filter "subject eq 'Important'"
foreach ($message in $messages) {
    Copy-MgUserMessage -UserId "user@domain.com" -MessageId $message.Id -DestinationId "AQMkAG..."
}
                                            

• Example 4: Copy All Messages

This example copies all messages from a user's mailbox to another folder.

$allMessages = Get-MgUserMessage -UserId "user@domain.com" -All
foreach ($message in $allMessages) {
    Copy-MgUserMessage -UserId "user@domain.com" -MessageId $message.Id -DestinationId "AQMkAG..."
}
                                            

Copy-MgUserMessage vs Move-MgUserMessage (Quick Comparison)

Feature	Copy-MgUserMessage	Move-MgUserMessage
Action	Copies the message	Moves the message
Original Message	Retained in source folder	Removed from source folder
Use Case	Compliance, duplication, backup	Cleanup, archiving, reorganization
Folder Impact	Message exists in multiple folders	Message exists in one folder
Data Safety	Non-destructive	Destructive to source location

Tip:
Use Copy-MgUserMessage when retention matters, and Move-MgUserMessage when mailbox cleanup is the goal.

Summary

Key Point	Details
Cmdlet Name	Copy-MgUserMessage
Purpose	Copies email messages between Outlook mail folders
Required Scope	Mail.ReadWrite
Target	User mailbox messages
Primary Parameters	UserId, MessageId, DestinationId
Automation Benefit	Enables message duplication without altering originals
Common Use Case	Compliance, backups, parallel mailbox organization