How to Use Get-Mailbox in Powershell

The Get-Mailbox cmdlet is one of the most widely used tools in Exchange Online and on-premises Exchange environments. It retrieves information about mailboxes and their properties, allowing administrators to view mailbox attributes, filter results, automate reports, and script management tasks in PowerShell.

What is the Get-Mailbox Cmdlet?

The Get-Mailbox cmdlet lets you retrieve mailbox objects from Exchange Online or Exchange Server. It provides access to mailbox-level information, such as Alias, DisplayName, EmailAddresses, Quota settings, and RecipientTypeDetails.

You can also use it with filters and pipeline logic to automate mailbox auditing, management, and reporting.

This cmdlet is part of the Exchange Online PowerShell module (EXO V2) or Exchange Management Shell for on-premises environments. It's essential for tasks like retrieving UserMailbox, SharedMailbox, RoomMailbox, or ArchiveMailbox details across tenants or within an on-premises organization.

Syntax

Get-Mailbox [-Identity <MailboxIdParameter>] [-Filter <String>] [-ResultSize <Unlimited or Integer>] [...]

You can also use it without the -Identity parameter to return all mailboxes (up to the limit set by -ResultSize).

Heads up: The -Filter parameter uses Exchange OPATH syntax - not regular PowerShell expressions.

Parameters

• Identity – Specify a mailbox using Alias, Email address, Display name, Distinguished Name, or GUID.
• Anr – Use Ambiguous Name Resolution to find mailboxes matching a partial name.
• Archive – Returns only mailboxes with archive mailboxes enabled.
• Filter – Apply a server-side OPATH filter as a string. Example: "RecipientTypeDetails -eq 'UserMailbox'".
• RecipientTypeDetails – Filter by mailbox type, e.g., SharedMailbox, UserMailbox, RoomMailbox, etc.
• ResultSize – Sets the maximum number of results. Use Unlimited for full queries.
• DomainController – (On-prem only) Specify the FQDN of a domain controller to retrieve mailbox data.
• OrganizationalUnit – (On-prem only) Search mailboxes within a specific Active Directory OU.
• ReadFromDomainController – (On-prem only) Force the command to get data directly from a domain controller.
• IncludeSoftDeletedRecipients – Returns mailboxes that are soft-deleted but still restorable.
• SortBy – (On-prem only) Sorts the results by a specific mailbox property.
• WhatIf / Confirm – Common switches to simulate or confirm the command's effect.
  

Key Differences: Get-Mailbox vs Get-ExoMailbox

If you're managing Exchange Online, Microsoft now recommends using Get-ExoMailbox instead of Get-Mailbox. Get-ExoMailbox is part of the Exchange Online PowerShell v2 module (EXO V2), which supports modern authentication, faster performance, and pagination for large datasets - all critical for handling mailboxes at scale in Microsoft 365.

We’ve covered Get-ExoMailbox in detail, including installation steps and performance tips, in this Get-ExoMailbox guide.

Practical Uses

Here are three real-world scenarios where Get-Mailbox is used regularly in Microsoft 365 or Exchange environments:

1. Audit All Shared Mailboxes in a Tenant

An IT admin needs a full list of SharedMailbox objects in the tenant for documentation, quota checks, or to ensure that none are being misused. Get-Mailbox lets you filter by RecipientTypeDetails and output attributes like DisplayName, EmailAddresses, or Quota for reporting or cleanup.

2. Monitor Mailbox Sizes Across Departments

Exchange admins often run scripts using Get-Mailbox in combination with Get-MailboxStatistics to track mailbox usage and enforce quota policies. This is critical in environments with limited storage or aggressive retention rules. Results are typically piped to Export-Csv for reporting.

3. Identify Inactive User Mailboxes for Deprovisioning

By combining Get-Mailbox with Last logon time pulled from Get-MailboxStatistics, you can detect UserMailbox objects that haven’t been accessed in months. This is key for license management, offboarding workflows, and compliance checks in Microsoft 365.

Prerequisites

Before using Get-Mailbox, make sure the following conditions are met:

• You have appropriate RBAC permissions, such as Recipient Management or View-Only Organization Management.
• For Exchange Online:
• Install the ExchangeOnlineManagement module.
• Connect using Connect-ExchangeOnline (MFA is required in most tenants).
• For on-premises Exchange:
• Use the Exchange Management Shell or a remote PowerShell session.
• You must have access to a domain controller and be authorized via RBAC.
• Admins do not need mailbox access to run Get-Mailbox, unless you're retrieving mailbox content (which this cmdlet does not do).
• Some parameters (e.g., DomainController, OrganizationalUnit) are only available in on-prem environments.
  

How to Use Get-Mailbox

This section walks through essential Get-Mailbox usage patterns in Exchange Online and on-premises Exchange. Each task includes the PowerShell command, the context, and how to modify it for different mailbox types or reporting needs.

1. Get a Specific Mailbox by Identity

Get-Mailbox -Identity "james@meetingroom365.com"

This retrieves all properties for a specific mailbox. Use it to inspect mailbox configuration like Alias, PrimarySmtpAddress, and RecipientTypeDetails, especially when investigating user issues or validating provisioning.

2. List All Mailboxes in the Tenant

Get-Mailbox -ResultSize Unlimited

The default result limit is 1,000. Use -ResultSize Unlimited to fetch every mailbox in the organization. This is essential for tenant-wide audits, reporting, or scripting tasks that loop through all users.

3. Filter by Mailbox Type (e.g. SharedMailbox)

Get-Mailbox -ResultSize Unlimited -Filter "RecipientTypeDetails -eq 'SharedMailbox'"

This filters mailboxes to only show those of type SharedMailbox. It’s useful when checking license status, mailbox delegation, or validating correct usage of shared inboxes. Other valid types include UserMailbox, RoomMailbox, EquipmentMailbox, etc.

4. Use Wildcard Matching on Display Name

Get-Mailbox -ResultSize Unlimited | Where-Object {$_.DisplayName -like "Sales*"}

Returns all mailboxes where the DisplayName starts with “Sales”. Useful when naming conventions reflect teams or roles. Note: this is a client-side filter  - inefficient for large tenants. Use server-side filtering (-Filter) when possible.

5. Export Mailbox Info to CSV

Get-Mailbox -ResultSize Unlimited -Filter "RecipientTypeDetails -eq 'UserMailbox'" | Select-Object DisplayName,Alias,PrimarySmtpAddress | Export-Csv -Path "C:\MailboxReport.csv" -NoTypeInformation

Exports selected mailbox fields to CSV for reporting, audits, or license tracking. This lets you build lightweight reports for stakeholders, or use mailbox data in external workflows. Add more fields like ProhibitSendQuota or CustomAttribute1 depending on your needs.

6. Get Archive Mailbox Status

Get-Mailbox -ResultSize Unlimited -Filter "ArchiveStatus -eq 'Active'"

Shows users with active archive mailboxes, often used for compliance, litigation hold, or storage management. Especially useful in regulated environments or when optimizing long-term mailbox growth.

7. Filter Mailboxes by Custom Attribute

Get-Mailbox -Filter "CustomAttribute1 -eq 'HR'"

Custom attributes (1–15) allow you to tag mailboxes with internal metadata. This lets you target specific departments, locations, or policy groups. Useful for automating policies, building distribution groups, or scoped reporting.

8. Show Specific Mailbox Properties

Get-Mailbox -Identity "james@meetingroom365.com" | Format-List

DisplayName,Alias,EmailAddresses,RecipientTypeDetails

Displays a clean, focused view of selected mailbox fields. Ideal when you only care about a few properties and want to avoid scanning through the entire object. Also good for debugging or script output cleanup.

That covers the key usage scenarios for Get-Mailbox in both Exchange Online and on-premises Exchange Server. This cmdlet is foundational to nearly every Exchange PowerShell script, especially when paired with other cmdlets like Get-MailboxStatistics, Export-Csv, or Format-List.