Using Remove-MgUserMessage in Graph PowerShell

This guide explains how to use the Remove-MgUserMessage cmdlet in Microsoft Graph PowerShell to delete email messages from a user’s mailbox. Learn how to remove single or multiple messages with practical examples and best practices.

Managing emails efficiently is a crucial task for IT administrators. The Remove-MgUserMessage cmdlet in Microsoft Graph PowerShell allows you to delete messages from a user's mailbox. This article covers the cmdlet's syntax, usage examples, tips, use cases, possible errors, and their solutions.

Cmdlet Syntax

Remove-MgUserMessage -UserId <String> -MessageId <String>

• UserId: The unique identifier of the user. It can be the user's UPN or User ID.
• MessageId: The unique identifier of the message to be deleted.

Usage Examples

Remove a Single Message by ID

Remove-MgUserMessage -UserId "user@domain.com" -MessageId "AAMkADhZD3KZAAA="

Note: Use Get-MgUserMessage cmdlet to get the message id.

Remove Multiple Messages

$messages = @("AAMkADhZD3KZAAA=", "AAMkADhZD3KZAAQ=")
foreach ($messageId in $messages) {
    Remove-MgUserMessage -UserId "user@domain.com" -MessageId $messageId
}

Note: Use Get-MgUserMessage cmdlet to get the message id.

Remove All Messages in a Folder

$folderMessages = Get-MgUserMessage -UserId "user@domain.com" -MailFolderId "AQMkADhZD3KZAAAA=" -All
foreach ($message in $folderMessages) {
    Remove-MgUserMessage -UserId "user@domain.com" -MessageId $message.Id
}

Note: Use Get-MgUserMailFolder cmdlet to get the mail folder id.

Remove Messages Based on a Condition

$oldMessages = Get-MgUserMessage -UserId "user@domain.com" -Filter "receivedDateTime lt 2023-01-01"
foreach ($message in $oldMessages) {
    Remove-MgUserMessage -UserId "user@domain.com" -MessageId $message.Id
}

Cmdlet Tips

• Use UserPrincipalName: You can use the user's email address as the UserId.
• Verify Message IDs: Ensure the MessageId is correct to avoid accidental deletions.
• Automate Cleanups: Use scripts to automate mailbox cleanups based on conditions such as date or subject.

Use Cases

• Mailbox Maintenance: Regularly clean up old or unwanted emails.
• Security Compliance: Remove sensitive information from mailboxes as needed.
• Automated Cleanup Tasks: Schedule scripts to run periodically and remove emails based on specified criteria.

Possible Errors & Solutions

Error: "Authentication_IdentityNotFound"

Cause: The specified UserId does not exist.

Solution: Verify the UserId and ensure the user exists in the tenant.

Error: "ResourceNotFound"

Cause: The specified MessageId does not exist.

Solution: Verify the MessageId and ensure the message exists in the user's mailbox.

Error: "ErrorInvalidArgument"

Cause: Invalid parameters passed to the cmdlet.

Solution: Ensure the UserId and MessageId are correctly formatted and valid.

Error: "ErrorAccessDenied"

Cause: Insufficient permissions to delete the message.

Solution: Ensure the executing account has the necessary permissions to delete messages in the specified mailbox. Mail.ReadWrite is the required graph api permission.

Frequently Asked Questions

1. What is Remove-MgUserMessage used for?

Remove-MgUserMessage is a Microsoft Graph PowerShell cmdlet used to delete email messages from a user’s mailbox, either individually or in bulk.

2. What permissions are required to use Remove-MgUserMessage?

You need the Mail.ReadWrite permission in Microsoft Graph PowerShell. Ensure these permissions are granted in Azure AD.

3. How can I delete all messages from a specific folder?

Use this script to delete all messages from a specific folder:

$Messages = Get-MgUserMailFolderMessage -UserId "" -MailFolderId "" -All
foreach ($Message in $Messages) {
    Remove-MgUserMessage -UserId "" -MessageId $Message.Id
}

Conclusion

The Remove-MgUserMessage cmdlet is a powerful tool for managing and cleaning up mailboxes in Microsoft 365. By understanding its syntax, usage examples, and potential errors, IT administrators can efficiently delete unwanted messages, ensuring mailboxes remain organized and secure.

Additional Resources:

Microsoft Graph PowerShell Module Documentation
Microsoft Graph API Documentation

Related Articles:

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