Skip to content

Commit 579e129

Browse files
Jr7468Jr7468
committed
feat: Add mailbox recipient limits standardization script
Add new PowerShell script to standardize mailbox recipient limits across tenants. This script will help enforce consistent recipient limits for mailboxes in the CIPP platform. Updated to use Bulk requests for more efficient handling. Updated to take Mailbox Plans into account to ensure we are not attempting to set values higher than mailbox plans are already set at. Tweak to account for the "Unlimited" default value Refactor mailbox recipient limits script to improve efficiency and accuracy. Consolidated mailbox plan retrieval and updated filtering logic to ensure only relevant mailboxes are processed based on recipient limits.
1 parent 8326331 commit 579e129

1 file changed

Lines changed: 180 additions & 0 deletions

File tree

‎Modules/CIPPCore/Public/Standards/Invoke-CIPPStandardMailboxRecipientLimits.ps1‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
function Invoke-CIPPStandardMailboxRecipientLimits {
2+
<#
3+
.FUNCTIONALITY
4+
Internal
5+
.COMPONENT
6+
(APIName) MailboxRecipientLimits
7+
.SYNOPSIS
8+
(Label) Set Mailbox Recipient Limits
9+
.DESCRIPTION
10+
(Helptext) Sets the maximum number of recipients that can be specified in the To, Cc, and Bcc fields of a message for all mailboxes in the tenant.
11+
(DocsDescription) This standard configures the recipient limits for all mailboxes in the tenant. The recipient limit determines the maximum number of recipients that can be specified in the To, Cc, and Bcc fields of a message. This helps prevent spam and manage email flow.
12+
.NOTES
13+
CAT
14+
Exchange Standards
15+
TAG
16+
ADDEDCOMPONENT
17+
{"type":"number","name":"standards.MailboxRecipientLimits.RecipientLimit","label":"Recipient Limit","defaultValue":500}
18+
IMPACT
19+
Low Impact
20+
ADDEDDATE
21+
2025-05-28
22+
POWERSHELLEQUIVALENT
23+
Set-Mailbox -RecipientLimits
24+
RECOMMENDEDBY
25+
"CIPP"
26+
#>
27+
28+
param($Tenant, $Settings)
29+
30+
# Input validation
31+
if ([Int32]$Settings.RecipientLimit -lt 0 -or [Int32]$Settings.RecipientLimit -gt 10000) {
32+
Write-LogMessage -API 'Standards' -tenant $Tenant -message 'MailboxRecipientLimits: Invalid RecipientLimit parameter set. Must be between 0 and 10000.' -sev Error
33+
return
34+
}
35+
36+
# Get mailbox plans first
37+
$MailboxPlans = New-ExoRequest -tenantid $Tenant -cmdlet 'Get-MailboxPlan' -cmdParams @{ ResultSize = 'Unlimited' }
38+
39+
# Create a hashtable of mailbox plans for quick lookup
40+
$MailboxPlanLookup = @{}
41+
foreach ($Plan in $MailboxPlans) {
42+
$MailboxPlanLookup[$Plan.Guid] = $Plan
43+
}
44+
45+
# Get mailboxes that need updating (either different from target limit or have "Unlimited" set)
46+
$Requests = @(
47+
@{
48+
CmdletInput = @{
49+
CmdletName = 'Get-Mailbox'
50+
Parameters = @{
51+
ResultSize = 'Unlimited'
52+
Filter = "RecipientLimits -ne '$($Settings.RecipientLimit)' -or RecipientLimits -eq 'Unlimited'"
53+
}
54+
}
55+
}
56+
)
57+
58+
$Mailboxes = New-ExoBulkRequest -tenantid $Tenant -cmdletArray $Requests
59+
60+
# Process mailboxes and categorize them based on their plan limits
61+
$MailboxResults = $Mailboxes | ForEach-Object {
62+
$Mailbox = $_
63+
$Plan = $MailboxPlanLookup[$Mailbox.MailboxPlanId]
64+
65+
if ($Plan) {
66+
$PlanMaxRecipients = $Plan.MaxRecipientsPerMessage
67+
68+
# If mailbox has "Unlimited" set but has a plan, use the plan's limit as the current limit
69+
$CurrentLimit = if ($Mailbox.RecipientLimits -eq 'Unlimited') {
70+
$PlanMaxRecipients
71+
}
72+
else {
73+
$Mailbox.RecipientLimits
74+
}
75+
76+
if ($Settings.RecipientLimit -gt $PlanMaxRecipients) {
77+
[PSCustomObject]@{
78+
Type = 'PlanIssue'
79+
Mailbox = $Mailbox
80+
CurrentLimit = $CurrentLimit
81+
PlanLimit = $PlanMaxRecipients
82+
PlanName = $Plan.DisplayName
83+
}
84+
}
85+
elseif ($CurrentLimit -ne $Settings.RecipientLimit) {
86+
[PSCustomObject]@{
87+
Type = 'ToUpdate'
88+
Mailbox = $Mailbox
89+
}
90+
}
91+
}
92+
elseif ($Mailbox.RecipientLimits -ne $Settings.RecipientLimit) {
93+
[PSCustomObject]@{
94+
Type = 'ToUpdate'
95+
Mailbox = $Mailbox
96+
}
97+
}
98+
}
99+
100+
# Separate mailboxes into their respective categories
101+
$MailboxesToUpdate = $MailboxResults | Where-Object { $_.Type -eq 'ToUpdate' } | Select-Object -ExpandProperty Mailbox
102+
$MailboxesWithPlanIssues = $MailboxResults | Where-Object { $_.Type -eq 'PlanIssue' } | ForEach-Object {
103+
[PSCustomObject]@{
104+
Identity = $_.Mailbox.Identity
105+
CurrentLimit = $_.CurrentLimit
106+
PlanLimit = $_.PlanLimit
107+
PlanName = $_.PlanName
108+
}
109+
}
110+
111+
# Remediation
112+
if ($Settings.remediate -eq $true) {
113+
if ($MailboxesWithPlanIssues.Count -gt 0) {
114+
Write-LogMessage -API 'Standards' -tenant $Tenant -message "Found $($MailboxesWithPlanIssues.Count) mailboxes where the requested recipient limit ($($Settings.RecipientLimit)) exceeds their mailbox plan limit. These mailboxes will not be updated." -sev Info
115+
foreach ($Mailbox in $MailboxesWithPlanIssues) {
116+
Write-LogMessage -API 'Standards' -tenant $Tenant -message "Mailbox $($Mailbox.Identity) has plan $($Mailbox.PlanName) with maximum limit of $($Mailbox.PlanLimit)" -sev Info
117+
}
118+
}
119+
120+
if ($MailboxesToUpdate.Count -gt 0) {
121+
try {
122+
# Create batch requests for mailbox updates
123+
$UpdateRequests = $MailboxesToUpdate | ForEach-Object {
124+
@{
125+
CmdletInput = @{
126+
CmdletName = 'Set-Mailbox'
127+
Parameters = @{
128+
Identity = $_.Identity
129+
RecipientLimits = $Settings.RecipientLimit
130+
}
131+
}
132+
}
133+
}
134+
135+
# Execute batch update
136+
$null = New-ExoBulkRequest -tenantid $Tenant -cmdletArray $UpdateRequests
137+
Write-LogMessage -API 'Standards' -tenant $Tenant -message "Successfully set recipient limits to $($Settings.RecipientLimit) for $($MailboxesToUpdate.Count) mailboxes" -sev Info
138+
}
139+
catch {
140+
$ErrorMessage = Get-CippException -Exception $_
141+
Write-LogMessage -API 'Standards' -tenant $Tenant -message "Could not set recipient limits. $($ErrorMessage.NormalizedError)" -sev Error -LogData $ErrorMessage
142+
}
143+
}
144+
else {
145+
Write-LogMessage -API 'Standards' -tenant $Tenant -message "All mailboxes already have the correct recipient limit of $($Settings.RecipientLimit)" -sev Info
146+
}
147+
}
148+
149+
# Alert
150+
if ($Settings.alert -eq $true) {
151+
if ($MailboxesToUpdate.Count -eq 0 -and $MailboxesWithPlanIssues.Count -eq 0) {
152+
Write-LogMessage -API 'Standards' -tenant $Tenant -message "All mailboxes have the correct recipient limit of $($Settings.RecipientLimit)" -sev Info
153+
}
154+
else {
155+
$AlertMessage = "Found $($MailboxesToUpdate.Count) mailboxes with incorrect recipient limits"
156+
if ($MailboxesWithPlanIssues.Count -gt 0) {
157+
$AlertMessage += " and $($MailboxesWithPlanIssues.Count) mailboxes where the requested limit exceeds their mailbox plan limit"
158+
}
159+
Write-StandardsAlert -message $AlertMessage -object ($MailboxesToUpdate + $MailboxesWithPlanIssues) -tenant $Tenant -standardName 'MailboxRecipientLimits' -standardId $Settings.standardId
160+
Write-LogMessage -API 'Standards' -tenant $Tenant -message $AlertMessage -sev Info
161+
}
162+
}
163+
164+
# Report
165+
if ($Settings.report -eq $true) {
166+
$ReportData = @{
167+
MailboxesToUpdate = $MailboxesToUpdate
168+
MailboxesWithPlanIssues = $MailboxesWithPlanIssues
169+
}
170+
Add-CIPPBPAField -FieldName 'MailboxRecipientLimits' -FieldValue $ReportData -StoreAs json -Tenant $Tenant
171+
172+
if ($MailboxesToUpdate.Count -eq 0 -and $MailboxesWithPlanIssues.Count -eq 0) {
173+
$FieldValue = $true
174+
}
175+
else {
176+
$FieldValue = $ReportData
177+
}
178+
Set-CIPPStandardsCompareField -FieldName 'standards.MailboxRecipientLimits' -FieldValue $FieldValue -Tenant $Tenant
179+
}
180+
}

0 commit comments

Comments
 (0)