PowerShell

Using Get-MgReportMailboxUsageDetail in Graph PowerShell

The Get-MgReportMailboxUsageDetail cmdlet is a useful tool for Microsoft 365 administrators to retrieve detailed reports on mailbox usage. This information is crucial for monitoring resource allocation, storage usage, and overall performance across the organization’s mailboxes.

Cmdlet Syntax

Get-MgReportMailboxUsageDetail -Period <Int32> -OutFile <String>

Required Parameters:

Period: Specifies the number of days over which the report should be generated. Valid values are between 1 and 180.
OutFile: Specifies the file path where the report will be saved.

Usage Example

Here’s an example of how to use the cmdlet to get a mailbox usage report for the past 90 days and export it to a CSV file:

Get-MgReportMailboxUsageDetail -Period 90 -OutFile "C:\Reports\MailboxUsageReport.csv"

This example generates a detailed report on mailbox usage over the past 90 days and saves it as a CSV file at the specified location.

Cmdlet Tips

Data Retention: Microsoft 365 limits the retention of usage data to 180 days, so you cannot retrieve reports for periods greater than 180 days.
Output File: Ensure the output file’s directory path exists, or you may face errors when attempting to save the report.
Execution Time: Reports with larger periods (e.g., 180 days) may take longer to generate, so plan accordingly when executing this cmdlet.

Frequently Asked Questions

What does Get-MgReportMailboxUsageDetail do?

This cmdlet retrieves detailed mailbox usage information for Microsoft 365 users, including storage size, item count, and last activity date. It helps administrators monitor mailbox growth and usage trends across the organization.

Why am I getting an error when using -Period D270?

The -Period parameter supports a maximum value of 180 days (D180). Using higher values like D270 or D365 results in an error. Always use supported durations such as D7, D30, D90, or D180.

Can I get mailbox usage details for a specific user only?

No. The report generated by Get-MgReportMailboxUsageDetail is organization-wide. However, you can filter the exported CSV file later in PowerShell or Excel to view a specific user’s data.

How often is mailbox usage data updated in Microsoft 365?

The mailbox usage data in Microsoft Graph reports is typically updated every 24 to 48 hours. This means recent mailbox activity might not appear instantly in the report.

Possible Errors & Solutions

Error	Cause	Solution
InvalidPeriodValue	The Period parameter value is outside the permissible range (1-180 days).	Ensure that the Period value does not exceed 180. For example, a valid period would be `-Period 180`, while an invalid one would be `-Period 200`. Adjust the value to be within the allowed range.
PathNotFoundException	The specified path in the OutFile parameter does not exist or is incorrect.	Verify that the directory specified in the OutFile path exists. You can create the directory manually or use PowerShell to create it:
CommandNotFoundException	The Get-MgReportMailboxUsageDetail cmdlet is not recognized.	Ensure that you have installed and imported the Microsoft Graph PowerShell module:

Use Cases

Storage Monitoring: Administrators can use this cmdlet to monitor mailbox usage across the organization and identify users who are close to exceeding their mailbox storage limits. This helps in proactive storage management and planning for upgrades.
Performance Optimization: By analyzing mailbox usage, administrators can identify mailboxes that are under heavy usage. This insight is valuable for optimizing resources and improving overall system performance.
Compliance Reporting: In regulated industries, maintaining audit trails of mailbox activity is essential for compliance. The usage details provided by this cmdlet can help generate reports for regulatory audits and compliance checks.
Cost Management: By tracking mailbox usage, organizations can determine which mailboxes are underutilized or overutilized, allowing for better license management and potential cost savings.

📅 Period Parameter Restriction

The -Period parameter in Get-MgReportMailboxUsageDetail accepts values only up to 180 days.
Attempting to specify a longer period (for example, D270) will return an error.

Always use valid period values such as D7, D30, D90, or D180 for successful report generation.

💾 Save Reports as CSV for Analysis

You can export mailbox usage data directly to a CSV file using the -OutFile parameter.

Get-MgReportMailboxUsageDetail -Period D30 -OutFile "C:\Reports\MailboxUsage.csv"

This helps administrators perform detailed analysis or share mailbox activity reports across teams easily.

Conclusion

The Get-MgReportMailboxUsageDetail cmdlet is an indispensable tool for administrators who need detailed insights into mailbox usage across their Microsoft 365 environment. By regularly running this report, you can optimize performance, manage storage, and ensure compliance within your organization. Just remember to keep the Period parameter within the 1-180 day range and ensure your output file path is correct to avoid common errors.

With the right use of this cmdlet, mailbox management becomes streamlined, helping you make informed decisions about your organization’s mailboxes.