The Remove-MgUserMailFolder cmdlet in the Microsoft Graph PowerShell module allows administrators to delete specific mail folders in a user's mailbox. This article provides a detailed overview of the cmdlet, including its syntax, usage examples, tips, use cases, possible errors, solutions, and a conclusion.
Remove-MgUserMailFolder -UserId <String> -MailFolderId <String> [-Confirm] [<CommonParameters>]Remove-MgUserMailFolder -UserId "user@domain.com" -MailFolderId "AAMkADI5AAAAAH0"Remove-MgUserMailFolder -UserId "user@domain.com" -MailFolderId "AAMkADI5AAAAAH0" -Confirm:$trueRemove-MgUserMailFolder -UserId "a1b2c3d4-e5f6-7890-ab12-cd34ef567890" -MailFolderId "AAMkADI5AAAAAH0"This helps clean up unused folders in a mailbox.
# Get all mail folders
$Folders = Get-MgUserMailFolder -UserId "john.doe@contoso.com" -All
foreach ($Folder in $Folders) {
# Check if folder has no messages
if ($Folder.TotalItemCount -eq 0) {
Write-Host "Deleting empty folder:" $Folder.DisplayName
Remove-MgUserMailFolder `
-UserId "john.doe@contoso.com" `
-MailFolderId $Folder.Id
}
}
This example deletes all subfolders under a given parent folder (e.g., a custom folder like “Projects”).
$UserId = "john.doe@contoso.com"
$ParentFolderName = "Projects"
# Get the parent folder
$ParentFolder = Get-MgUserMailFolder `
-UserId $UserId `
-Filter "displayName eq '$ParentFolderName'"
if ($ParentFolder) {
# Get all child folders under the parent
$ChildFolders = Get-MgUserMailFolderChildFolder `
-UserId $UserId `
-MailFolderId $ParentFolder.Id `
-All
foreach ($Folder in $ChildFolders) {
Write-Host "Deleting subfolder:" $Folder.DisplayName
Remove-MgUserMailFolder `
-UserId $UserId `
-MailFolderId $Folder.Id
}
}
else {
Write-Host "Parent folder not found."
}
| Error | Cause | Solution |
|---|---|---|
| Access Denied | Insufficient permissions to delete the mail folder. | Ensure that the account executing the cmdlet has the required permissions. Assign the necessary permissions to the account using appropriate admin roles. |
| MailFolderNotFound | The specified MailFolderId does not exist in the user's mailbox. | Verify the MailFolderId and ensure it is correct. Use Get-MgUserMailFolder to list all mail folders and confirm the folder ID. |
| UserNotFound | The specified UserId does not exist or is incorrect. | Ensure that the UserId is correct and the user exists in the directory. Validate the UserId using Get-MgUser. |
The Remove-MgUserMailFolder cmdlet is a powerful tool for administrators to manage and clean up mail folders in user mailboxes. By understanding its syntax, usage examples, tips, use cases, and troubleshooting common errors, you can effectively utilize this cmdlet to maintain mailbox hygiene and compliance. Always double-check the parameters and use the -Confirm parameter to avoid accidental deletions.
Leverage this cmdlet to streamline your mailbox management tasks and enhance the overall efficiency of your organization's email system.
You can use the Microsoft Graph API directly via Invoke-MgGraphRequest to delete a mail folder. Below is the complete example demonstrating how to remove a user’s mail folder by ID and handle the output in a proper and consistent way using PowerShell.
Example: Remove a Mail Folder by ID
This example demonstrates how to delete a specific mail folder for a user by passing the UserId and MailFolderId.
# Define the user and mail folder ID
$userId = "user@domain.com"
$mailFolderId = "AAMkADI5AAAAAH0"
# Build the URI for the Graph API DELETE request
$uri = "https://graph.microsoft.com/v1.0/users/$userId/mailFolders/$mailFolderId"
# Make the DELETE request to remove the mail folder
try {
$response = Invoke-MgGraphRequest -Method DELETE -Uri $uri
# Check if the response contains a 'value' property and loop through it
if ($response.value) {
foreach ($item in $response.value) {
Write-Output "Deleted Mail Folder:"
Write-Output "ID : $($item.id)"
Write-Output "Display Name: $($item.displayName)"
Write-Output "`n"
}
} else {
Write-Output "Mail folder deleted successfully or no content returned in response."
}
} catch {
Write-Output "Failed to delete mail folder. Error: $($_.Exception.Message)"
}
How It Works
mailFolders endpoint with the user's ID and folder ID.try/catch to capture any failure (e.g., invalid ID, insufficient permissions).value array, we loop through it and print folder details. Most DELETE operations return an empty body (204 No Content), so the fallback message confirms successful execution.Microsoft Graph API Reference
© Created and Maintained by LEARNIT WELL SOLUTIONS. All Rights Reserved.