PowerShell

Using Update-MgUserMessage in Graph PowerShell

The Update-MgUserMessage cmdlet allows administrators to modify messages within a user's mailbox using Microsoft Graph PowerShell. This cmdlet is particularly useful for updating properties such as categories, importance, or flagging messages.

In this article, we’ll explore the syntax, usage examples, common errors, and use cases to help you efficiently use this cmdlet for mailbox management tasks.

Cmdlet Syntax

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

Parameters:

UserId: The unique identifier (or UPN) of the user whose message you are updating.
MessageId: The unique identifier of the message you want to modify.
BodyParameter: The set of properties to update, provided in a hashtable format.

Usage Examples

Example 1: Update the Importance of a Message

In this example, we update the importance of a specific message to "High".

$params = @{
    importance = "high"
}

Update-MgUserMessage -UserId "johndoe@contoso.com" -MessageId "AAMkADh...==" -BodyParameter $params

Example 2: Flag a Message for Follow-Up

Here, we flag a message for follow-up.

$params = @{
    flag = @{
        flagStatus = "flagged"
    }
}

Update-MgUserMessage -UserId "janedoe@contoso.com" -MessageId "AAMkADM...==" -BodyParameter $params

Example 3: Categorize a Message

This example adds a category to a message for better organization.

$params = @{
    categories = @("Work", "Important")
}

Update-MgUserMessage -UserId "marksmith@contoso.com" -MessageId "AAMkAGL...==" -BodyParameter $params

Cmdlet Tips

BodyParameter Hashtable: Always ensure that the hashtable follows the correct syntax as laid out in Microsoft documentation. Incorrectly formatted hashtables will result in errors.
Message ID Retrieval: Use the Get-MgUserMessage cmdlet to retrieve message IDs before updating the message.
Test in Small Batches: When performing updates in bulk, test on a few messages first to ensure the changes are correct.

Possible Errors & Solutions

Error	Cause	Solution
InvalidAuthenticationToken	The token being used for authentication is invalid or expired.	Refresh your authentication token by re-running the Connect-MgGraph cmdlet and signing in again.
ResourceNotFound	The specified message ID is incorrect or the message doesn’t exist in the user’s mailbox.	Verify the MessageId using Get-MgUserMessage to ensure the message exists and that the correct ID is used.
Request_BadRequest	The BodyParameter hashtable is incorrectly formatted.	Double-check the format of the hashtable. Ensure you follow the conventions provided in the Microsoft documentation, especially for nested parameters like flag or dueDateTime.

Use Cases

Follow-up on Important Tasks: Administrators can flag emails for users who need follow-ups on critical tasks. Automating this can help users stay on track without manually reviewing their inbox.
Automated Message Categorization: Automatically assign categories to emails based on specific criteria (e.g., sender or subject keywords) to enhance organization within a user's mailbox.
Priority Adjustment for Key Communications: In cases where certain communications need immediate attention, admins can elevate the importance of emails to ensure that users address them promptly.

Conclusion

The Update-MgUserMessage cmdlet is a powerful tool for modifying messages in a user’s mailbox. Whether flagging messages, setting categories, or adjusting the importance, it provides flexibility in managing email communication.

Be mindful of the BodyParameter format and ensure accurate MessageId and UserId inputs to avoid common errors. This cmdlet is an essential part of an admin’s toolkit for optimizing and automating mailbox management.