PowerShell

Using Get-MgUserMessageCount in Graph PowerShell

This guide explains how to use the Get-MgUserMessageCount cmdlet in Microsoft Graph PowerShell to count user mailbox messages and export count data for analysis.

The Get-MgUserMessageCount cmdlet is a powerful tool for administrators working with Microsoft Graph PowerShell. It allows you to quickly retrieve the total number of email messages in a user's mailbox. Whether you are tracking mailbox usage, generating reports, or performing audits, this cmdlet simplifies the task by providing a count of the user's messages. In this article, we’ll explore its syntax, practical usage examples, and advanced scenarios to maximize its potential.

Cmdlet Syntax

Get-MgUserMessageCount -UserId  <String>

-UserId: The unique identifier (or UPN) of the user whose message count you want to retrieve.

Usage Examples

Example 1: Get Total Message Count for a Specific User

This example retrieves the total number of messages in the mailbox of a specific user by using their User Principal Name (UPN).


Get-MgUserMessageCount -UserId "jane.doe@yourdomain.com"

Example 2: Get Message Count and Log Results for Multiple Users

You can loop through a list of users (from a CSV file, for example) and log their message count into a report file.


        # Import a CSV of user UPNs and get message counts for all users
        $users = Import-Csv "C:\UsersList.csv"
        foreach ($user in $users) {
            $count = Get-MgUserMessageCount -UserId $user.UserPrincipalName
            Add-Content -Path "C:\MessageCountReport.txt" -Value "$($user.UserPrincipalName): $count messages"
        }

Cmdlet Tips

Filter Unnecessary Data: The cmdlet only returns a single value—the message count—which simplifies processing and storage of the data.
CSV Imports for Bulk Operations: : For organizations managing multiple users, importing a CSV with user details is an efficient way to loop through multiple user mailboxes and retrieve message counts.
User Principal Name (UPN): The UserId can either be the user’s UPN (email address) or their unique Azure AD User ID. Ensure you have the correct identifier to avoid common errors.

Possible Errors & Solutions

Error	Cause	Solution
Invalid UserId	The UserId provided may be incorrect, or the user does not exist in your tenant.	Double-check the UserId (UPN or user ID) format. You can verify it using the Get-MgUser cmdlet to ensure you are targeting the correct user.`Get-MgUserMessage` cmdlet to list messages in the user's mailbox and find the required ID.
Insufficient Permissions	The account executing the command lacks the required permissions to access the user’s mailbox data.	Ensure the user account has the correct permissions, such as the Mail.ReadBasic or Mail.Read permission in Microsoft Graph. Verify the permissions assigned using Azure AD.
Too Many Requests	This error occurs if the script is making too many requests to Microsoft Graph in a short period of time.	Introduce a delay between requests (using Start-Sleep cmdlet) to avoid hitting the request rate limit. Microsoft Graph also supports throttling, so respecting the usage limits ensures smoother execution.

Use Cases

Auditing Mailbox Usage: For organizations that need to audit mailbox usage regularly, this cmdlet provides a simple and effective way to count the number of messages in user mailboxes. You can automate this process to generate weekly or monthly reports on mailbox usage, identifying users who may need mailbox optimization or storage expansion.


    # Generate a weekly report of user message counts
        $users = Get-MgUser -All
        foreach ($user in $users) {
            $messageCount = Get-MgUserMessageCount -UserId $user.UserPrincipalName
            Add-Content -Path "C:\MailboxAudit\WeeklyReport.txt" -Value "$($user.UserPrincipalName): $messageCount messages"
        }

Identifying High Email Volume Users: In large organizations, certain users may handle significantly more emails than others, such as customer service teams or executives. Tracking message counts can help you identify high-volume users and optimize their email experience by archiving old emails or increasing their mailbox quota.


    # Identify high-volume email users with over 10,000 emails
        $users = Get-MgUser -All
        foreach ($user in $users) {
            $messageCount = Get-MgUserMessageCount -UserId $user.UserPrincipalName
            if ($messageCount -gt 10000) {
                Write-Host "$($user.UserPrincipalName) has $messageCount emails and may need mailbox optimization."
            }
        }

Frequently Asked Questions

What is Get-MgUserMessageCount used for?

Get-MgUserMessageCount is a Microsoft Graph PowerShell cmdlet used to retrieve the total count of messages in a user’s mailbox. It supports filtering to count specific types of messages, such as unread or from a particular sender.

How can I count the total messages in a user’s mailbox?

To count all messages in a user’s mailbox, use the following command:

Get-MgUserMessageCount -UserId "<UserPrincipalName>"

How can I count messages in a specific folder?

You can count messages in a specific folder by including the folder ID. Example:

Get-MgUserMessageCount -UserId "<UserPrincipalName>" -MailFolderId "<FolderId>"

How can I count unread messages?

Use the -Filter parameter to count unread messages:

Get-MgUserMessageCount -UserId "<UserPrincipalName>" -Filter "isRead eq false"

Conclusion

The Get-MgUserMessageCount cmdlet is a simple yet powerful tool for monitoring and managing mailbox usage in Microsoft 365 environments. With just a few lines of PowerShell, administrators can retrieve message counts for individual users or scale up the operation to analyze mailbox usage across the entire organization. By integrating this cmdlet into regular reporting and audit routines, you can optimize email storage and streamline organizational email management.

Take advantage of this cmdlet to improve your email workflows, track user activity, and ensure that your organization’s mailboxes are operating efficiently.

Additional Resources:

Graph PowerShell Get-MgUserMessageCount Cmdlet Documentation
Microsoft Graph PowerShell Module Documentation
Microsoft Graph API Documentation

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