PowerShell: Exchange Online – Report Mailboxes Approaching Their Quota

Connect-ExchangeOnline -ShowBanner:$false
.\Get-MailboxQuotaReport.ps1

.\Get-MailboxQuotaReport.ps1 -WarningPercent 90 -RecipientTypeDetails UserMailbox -OutputPath 'C:\Reports\mailbox-quota.csv'

Connect-ExchangeOnline -CertificateThumbprint '<thumbprint>' -AppId '<application-id>' -Organization '<tenant>.onmicrosoft.com' -ShowBanner:$false
.\Get-MailboxQuotaReport.ps1 -OutputPath 'C:\Reports\mailbox-quota.csv'
Disconnect-ExchangeOnline -Confirm:$false

Checked 1,184 mailbox(es); 4 at or above 80% of ProhibitSendQuota.

DisplayName        Type          UsedGB QuotaGB PercentUsed RecoverableGB RecoverablePercent ArchiveEnabled
-----------        ----          ------ ------- ----------- ------------- ------------------ --------------
<display-name>     UserMailbox     48.9    49.5        98.8           2.1                7.0 False
<display-name>     UserMailbox     91.3    99.0        92.2          88.6               88.6 True
<display-name>     UserMailbox     84.0    99.0        84.8          11.4               38.0 False
<display-name>     UserMailbox     79.6    99.0        80.4           0.9                3.0 True

<#
.SYNOPSIS
    Reports Exchange Online mailboxes approaching their send quota.
.DESCRIPTION
    Enumerates mailboxes with Get-EXOMailbox (Quota and Archive property sets), reads each mailbox's
    TotalItemSize and TotalDeletedItemSize with Get-EXOMailboxStatistics, and returns the mailboxes
    at or above a percentage of ProhibitSendQuota, with Recoverable Items usage against
    RecoverableItemsQuota alongside. Sorted with the most urgent mailboxes first. Optionally exports
    the report to CSV.
.PARAMETER WarningPercent
    Percentage of ProhibitSendQuota used that puts a mailbox in the report. Defaults to 80.
.PARAMETER RecipientTypeDetails
    Mailbox types to check. Defaults to UserMailbox and SharedMailbox.
.PARAMETER OutputPath
    CSV path to export the report to. If omitted, the report only prints to the console.
.EXAMPLE
    .\Get-MailboxQuotaReport.ps1 -WarningPercent 90 -OutputPath 'C:\Reports\mailbox-quota.csv'
.NOTES
    Author  : Thomas Lasswell (https://www.techcolumnist.com)
    Version : 1.0 (2025-09-03)
    Requires: ExchangeOnlineManagement 3.0.0 or later, an active Connect-ExchangeOnline session
#>
[CmdletBinding()]
param (
    [Parameter(Mandatory = $false)]
    [ValidateRange(1, 100)]
    [int]$WarningPercent = 80,

    [Parameter(Mandatory = $false)]
    [string[]]$RecipientTypeDetails = @('UserMailbox', 'SharedMailbox'),

    [Parameter(Mandatory = $false)]
    [string]$OutputPath
)

function ConvertTo-ByteCount {
    param ($Size)

    # Quotas and sizes arrive either as a ByteQuantifiedSize (with ToBytes()) or as its
    # string form, for example "4.92 GB (5,283,165,983 bytes)". "Unlimited" returns $null.
    if ($null -eq $Size) {
        return $null
    }
    if ($Size.PSObject.Properties['Value'] -and $Size.Value -and $Size.Value.PSObject.Methods['ToBytes']) {
        return [double]$Size.Value.ToBytes()
    }
    $text = $Size.ToString()
    if ($text -match '\(([\d,.\s]+) bytes\)') {
        return [double]($Matches[1] -replace '[^\d]', '')
    }
    return $null
}

if (-not (Get-ConnectionInformation)) {
    throw 'No Exchange Online session. Run Connect-ExchangeOnline first.'
}

Write-Verbose 'Retrieving mailboxes'
$mailboxes = Get-EXOMailbox -ResultSize Unlimited -RecipientTypeDetails $RecipientTypeDetails -PropertySets Quota, Archive

$checked = 0
$report = foreach ($mailbox in $mailboxes) {
    $quotaBytes = ConvertTo-ByteCount -Size $mailbox.ProhibitSendQuota
    if (-not $quotaBytes) {
        # Unlimited quota: nothing to measure against.
        continue
    }

    # Never pass an empty identity: a $null Identity returns statistics for every mailbox.
    if ([string]::IsNullOrWhiteSpace($mailbox.UserPrincipalName)) {
        continue
    }

    try {
        $stats = Get-EXOMailboxStatistics -UserPrincipalName $mailbox.UserPrincipalName -ErrorAction Stop
    } catch {
        Write-Warning "Could not read statistics for $($mailbox.UserPrincipalName): $($_.Exception.Message)"
        continue
    }
    $checked++

    $usedBytes = ConvertTo-ByteCount -Size $stats.TotalItemSize
    if ($null -eq $usedBytes) {
        continue
    }

    $percentUsed = [math]::Round(($usedBytes / $quotaBytes) * 100, 1)
    if ($percentUsed -lt $WarningPercent) {
        continue
    }

    $deletedBytes = ConvertTo-ByteCount -Size $stats.TotalDeletedItemSize
    $recoverableQuotaBytes = ConvertTo-ByteCount -Size $mailbox.RecoverableItemsQuota
    $recoverablePercent = $null
    if ($deletedBytes -and $recoverableQuotaBytes) {
        $recoverablePercent = [math]::Round(($deletedBytes / $recoverableQuotaBytes) * 100, 1)
    }

    [PSCustomObject]@{
        DisplayName        = $mailbox.DisplayName
        Mailbox            = $mailbox.PrimarySmtpAddress
        Type               = $mailbox.RecipientTypeDetails
        UsedGB             = [math]::Round($usedBytes / 1GB, 1)
        QuotaGB            = [math]::Round($quotaBytes / 1GB, 1)
        PercentUsed        = $percentUsed
        RecoverableGB      = if ($deletedBytes) { [math]::Round($deletedBytes / 1GB, 1) } else { 0 }
        RecoverablePercent = $recoverablePercent
        ArchiveEnabled     = $mailbox.ArchiveStatus -eq 'Active'
    }
}

$sortedReport = @($report | Sort-Object -Property PercentUsed -Descending)

Write-Host ("Checked {0:N0} mailbox(es); {1} at or above {2}% of ProhibitSendQuota." -f $checked, $sortedReport.Count, $WarningPercent)
$sortedReport | Format-Table -Property DisplayName, Type, UsedGB, QuotaGB, PercentUsed, RecoverableGB, RecoverablePercent, ArchiveEnabled -AutoSize

if ($OutputPath) {
    $sortedReport | Export-Csv -Path $OutputPath -NoTypeInformation -Encoding UTF8
    Write-Host "Report exported to $OutputPath"
}