PowerShell

Manage Outlook Email Categories with Graph PowerShell

Email categories are a powerful tool in Outlook that help users organize their mailboxes by tagging emails with specific labels and colors. Categories allow users to quickly identify important messages, group related conversations, and streamline email management. For administrators, having the ability to view and manage these categories can be essential, especially when assisting users or monitoring mailbox organization.

The Script: Retrieve Email Categories from a User's Mailbox

# Connect to Microsoft Graph
Connect-MgGraph -Scopes "MailboxSettings.Read"

# Define the user whose categories you want to retrieve
$UserId = "user@yourdomain.com"

# Retrieve email categories from the user's mailbox using Get-MgUserOutlookMasterCategory
$categories = Get-MgUserOutlookMasterCategory -UserId $UserId

# Display the list of categories
if ($categories.Count -gt 0) {
    Write-Host "Email Categories for $UserId:"
    $categories | Select-Object DisplayName Color | Format-Table
} else {
    Write-Host "No categories found in $UserId's mailbox."
}

# Disconnect from Microsoft Graph
Disconnect-MgGraph

How the Script Works

Connect-MgGraph: The script begins by connecting to Microsoft Graph with the required permission MailboxSettings.Read, which allows it to read the mailbox settings of the specified user.
Define the User: The $UserId variable specifies the email address of the user whose mailbox categories are being queried.
Retrieve Email Categories: The Get-MgUserOutlookMasterCategory cmdlet is used to retrieve the list of categories from the user's mailbox. This cmdlet directly accesses the categories that are used in Outlook to tag and organize emails.
Display the Results: If categories are found, they are displayed in a table format showing the DisplayName (the name of the category) and the associated Color. If no categories are found, the script informs you that the mailbox does not have any categories configured.
Disconnect-MgGraph: Finally, the script disconnects from Microsoft Graph, ending the session securely.

Further Enhancements

Create New Categories: You can add functionality to create new categories if they do not exist. By combining this with the New-MgUserOutlookMasterCategory cmdlet, you can automate category creation across multiple users.

$newCategory = @{
    displayName = "Important Updates"
    color = "preset9"
}
New-MgUserOutlookMasterCategory -UserId $UserId -BodyParameter $newCategory

Delete or Update Categories: You can add logic to delete outdated categories or update the color of existing categories. This can help users better organize their inbox by automating mailbox management.
Automate Category Monitoring: Set up a scheduled task that periodically checks for users’ category usage, ensuring consistent mailbox organization. This can be done using Task Scheduler or Azure Automation.
Export Category Data to CSV: Modify the script to export the list of categories to a CSV file for reporting or analysis purposes.

$categories | Export-Csv -Path "C:\Reports\UserCategories.csv" -NoTypeInformation

Possible Errors & Solutions

Error	Cause	Solution
Insufficient privileges to complete the operation.	The connected account does not have the necessary permissions to access mailbox settings.	Ensure the account has been granted the MailboxSettings.Read or MailboxSettings.ReadWrite permissions in Azure AD. Admin consent might be required for these permissions.
No categories found	The user might not have any categories configured in their mailbox.	Confirm that the user has created categories in Outlook. You can also create a test category using the New-MgUserOutlookMasterCategory cmdlet to ensure categories are set up.
The term 'Get-MgUserOutlookMasterCategory' is not recognized.	The Microsoft Graph PowerShell module might not be installed or updated.	Install or update the Microsoft Graph PowerShell module using the following command:
Unauthorized or expired session	The Graph API token may have expired.	Ensure you reconnect to Microsoft Graph with valid credentials and the correct permissions before running the script.

Check and Reuse Category Names to Avoid Duplication

Before you create a new category for a user, it’s smart to first retrieve the existing list (via Get-MgUserOutlookMasterCategory) and compare. This avoids creating duplicate names or slightly changed variants like “Project A” vs “Project_A” which can clutter mailbox organization. Tip: Export the category list once per user to a CSV, then compare new list entries against it in your automation.

Application Permissions Required for Shared or Multiple Mailboxes

If you plan to run this script against many users or shared mailboxes (rather than the currently logged-in user only), you’ll likely need to use application permission MailboxSettings.ReadWrite rather than only delegated permission. Without that, you’ll hit "AccessDenied" errors when reading categories of another user. Tip: Create an AAD app registration with the required application scope, grant admin consent, and then use certificate/secret auth — especially if doing mass user category management.

Conclusion

Managing email categories in Outlook is an important aspect of mailbox organization, and with Microsoft Graph PowerShell, administrators can easily retrieve and monitor these categories for users. This script offers a quick and efficient way to view existing categories, and with further enhancements, it can be extended to automate other aspects of category management.

By implementing this solution, administrators can help ensure that users are effectively organizing their mailboxes, making email management more efficient and reducing clutter.

Try using this script to monitor and manage email categories in your organization, and feel free to expand its functionality to meet your specific requirements!