M365 PowerShell

Using Copy-MgUserMessage in Graph PowerShell

The Copy-MgUserMessage cmdlet in Microsoft Graph PowerShell is a powerful tool that allows administrators to copy email messages from one folder to another within a user's mailbox. This cmdlet is particularly useful for managing and organizing emails in bulk or based on specific conditions.

Note: You need mail folder ID and message ID to work with this cmdlet. Use Get-MgUserMailFolder and Get-MgUserMailFolderMessage cmdlets to get the IDs.

Cmdlet Syntax

Copy-MgUserMessage -UserId <String> -MessageId <String> -DestinationId <String> [-WhatIf] [-Confirm]

-UserId: The ID or UPN of the user.
-MessageId: The ID of the message to be copied.
-DestinationId: The ID of the destination folder.
-WhatIf: Shows preview of how the cmdlet works without executing the cmdlet.
-Confirm: Helps double-check the action of copying messages.

Usage 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..."
}

Cmdlet Tips

Efficiency: When copying multiple messages, ensure you optimize the process by retrieving only the necessary messages using filters.
BodyParameter Usage: While it's optional, the -BodyParameter can be used to pass additional properties if required.
Error Handling: Consider adding error handling to your scripts to manage scenarios where messages might not be found or the destination folder doesn't exist.

Possible Errors & Solutions

Error: The specified message ID was not found.

Cause: The MessageId provided does not exist in the user's mailbox.

Solution: Verify that the MessageId is correct. You can use the Get-MgUserMessage cmdlet to list messages and confirm the ID.

Error: The destination folder ID is invalid.

Cause: The DestinationId does not correspond to a valid folder in the user's mailbox.

Solution: Ensure that the DestinationId is accurate. You can use Get-MgUserMailFolder to retrieve and verify folder IDs.

Error: Insufficient permissions to perform the operation.

Cause: The account running the cmdlet lacks the necessary permissions to copy messages.

Solution: Confirm that the account has the required permissions. The user might need the Mail.ReadWrite permission.

Error: Operation timed out.

Cause: The operation took too long to complete, possibly due to the large number of messages.

Solution: Break down the operation into smaller batches or optimize the message retrieval process.

Use Cases

Email Organization: Administrators can automate the process of organizing emails by copying specific messages to designated folders based on subject, sender, or other criteria.
Mailbox Migration: During mailbox migrations, the Copy-MgUserMessage cmdlet can help move emails from one folder structure to another, ensuring that users maintain access to their important messages.
Compliance & Auditing: For compliance purposes, emails can be copied to a secure folder for long-term storage or auditing.

Conclusion

The Copy-MgUserMessage cmdlet is a versatile tool in the Microsoft Graph PowerShell module that simplifies email management within user mailboxes. By leveraging this cmdlet, administrators can efficiently handle various tasks such as bulk copying, filtering, and organizing emails, ensuring smooth operations and adherence to compliance requirements. Understanding the cmdlet's syntax, potential errors, and use cases will enable you to make the most of its capabilities in your day-to-day administrative tasks.

Additional Resources:

Copy-MgUserMessage Cmdlet Documentation
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