Get-MgUserMessageCount

What is Get-MgUserMessageCount?

Get-MgUserMessageCount is a Microsoft Graph PowerShell cmdlet used to retrieve the total number of email messages in a user’s mailbox. Instead of returning full message objects, this cmdlet efficiently returns only the count, making it ideal for reporting and analytics.

It supports OData filters, allowing administrators to count messages based on conditions such as read status, folder, or date range.

Why Use Get-MgUserMessageCount?

Administrators use Get-MgUserMessageCount to:

• Generate mailbox usage statistics
• Count unread or filtered emails without fetching message data
• Improve performance in large mailboxes
• Support reporting, auditing, and monitoring scripts
• Reduce API payload size when only counts are needed

This cmdlet is especially useful for lightweight reporting and automation dashboards.

Prerequisites

Before using this cmdlet, ensure:

• Microsoft Graph PowerShell module is installed
• You are connected to Microsoft Graph
• Required permission scope is granted

Connect-MgGraph -Scopes "Mail.Read"

How to use Get-MgUserMessageCount?

Basic syntax:

Get-MgUserMessageCount -UserId <String> [-Filter  <String>]

• UserId: User Principal Name (UPN) or User ID
• Filter(optional): OData filter to refine message count

Get-MgUserMessageCount Examples

• Get Total Message Count

Get-MgUserMessageCount  -UserId "user@domain.com"

This example retrieves the total count of messages in the specified user's mailbox.

• Get Message Count with a Filter

Get-MgUserMessageCount -UserId "user@domain.com" -Filter "isRead eq false"

This example retrieves the count of unread messages in the user's mailbox

• Get Message Count from a Specific Folder

Get-MgUserMessageCount -UserId "user@domain.com" -Filter "parentFolderId eq 'AAMkAGI2TAAA='"

This example retrieves the count of messages in a specific mail folder using its folder ID. Use the Get-MgUserMailFolder cmdlet to retrieve the folder ID.

• Get Message Count for a Specific Time Range

Get-MgUserMessageCount -UserId "user@domain.com" `-Filter "receivedDateTime ge 2023-01-01T00:00:00Z and receivedDateTime le 2023-12-31T23:59:59Z"

This example retrieves the count of messages received within a defined date range.

Get-MgUserMessageCount vs Get-MgUserMessage

Cmdlet	Purpose	Output	When to Use
Get-MgUserMessageCount	Returns the number of messages in a mailbox	Integer (count only)	When you only need statistics, trends, or quick counts
Get-MgUserMessage	Retrieves full email message objects	Message details (subject, sender, body, etc.)	When you need to read, move, copy, or analyze messages

Key Difference

• Get-MgUserMessageCount is optimized for performance and reporting
• Get-MgUserMessage is designed for content-level operations
👉 Best practice: Use Get-MgUserMessageCount whenever message details are not required to avoid unnecessary data retrieval and improve script efficiency.

Summary

Key Point	Details
Cmdlet Name	Get-MgUserMessageCount
Purpose	Retrieves message count from a user mailbox
Required Scope	Mail.Read
Data Returned	Integer count only
Supports Filters	Yes (OData)
Performance	High (no message objects returned)
Common Use Cases	Reporting, analytics, mailbox monitoring