m365Corner
Home / M365 PowerShell / Update-MgUserMessage
M365 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.

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

Example 4: Mark a Message as Read


$params = @{
    isRead = $true
}
Update-MgUserMessage `
    -UserId "johndoe@contoso.com" `
    -MessageId "AAMkADh...==" `
    -BodyParameter $params

What this script does

This script updates the isRead property of a specific email message and marks it as read.

Why this example is useful

This is useful for mailbox automation scenarios where admins want to mark processed alerts, system-generated emails, or handled support notifications as read after automation completes.

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.

Frequently Asked Questions

  • Can I mark an email as read using Update-MgUserMessage?

    • Yes. Set the isRead property to $true.

    
$params = @{    
  isRead = $true
}

Update-MgUserMessage -UserId "user@domain.com" -MessageId "MESSAGE-ID" 
-BodyParameter $params
  • Can I mark an email as unread using Update-MgUserMessage?
    • 
Yes. Set isRead to $false.

$params = @{    
  isRead = $false
}Update-MgUserMessage -UserId "user@domain.com" -MessageId "MESSAGE-ID" 
-BodyParameter $params
  • Can Update-MgUserMessage change the email subject or body?

    • No. Update-MgUserMessage is mainly useful for updating writable message properties such as importance, isRead, categories, and flag. It should not be treated as a cmdlet for rewriting delivered email content.

  • Do I need the MessageId before using Update-MgUserMessage?

    • Yes. You need the message ID of the email you want to update. You can retrieve it using Get-MgUserMessage.

    
Get-MgUserMessage -UserId "user@domain.com" |
Select-Object Subject, Id
  • Does Update-MgUserMessage move the email to another folder?

    • No. To move a message, use Move-MgUserMessage. Update-MgUserMessage updates message properties; it does not move the message between folders.


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.

Suggested Reading