How to Use PowerShell New-InboxRule to Deploy Rules Across User Mailboxes

Managing inbox rules for multiple users in Exchange Online or Exchange Server can be time-consuming when done manually. You need to create, update, or replace rules for dozens or hundreds of mailboxes without opening each user’s Outlook. The PowerShell cmdlet New-InboxRule lets you automate this task directly from the Exchange Management Shell or Exchange Online PowerShell module. This article explains how to deploy inbox rules across user mailboxes using New-InboxRule, including prerequisites, step-by-step commands, and common mistakes to avoid.

Understanding New-InboxRule and Its Requirements

New-InboxRule is an Exchange PowerShell cmdlet that creates a server-side inbox rule for a specified mailbox. The rule runs on the Exchange server or in Exchange Online, so it works even when the user’s Outlook is closed. The cmdlet supports common conditions such as sender address, subject keywords, and recipient address, and actions like moving to a folder, forwarding, or deleting.

Before using New-InboxRule, you must meet these requirements:

• PowerShell module: Install the Exchange Online PowerShell V2 module (EXO V2) for cloud mailboxes, or connect to an on-premises Exchange Management Shell.
• Permissions: You need the Mail Recipients role or be a member of the Organization Management or Recipient Management role group.
• Mailbox type: The target mailbox must be a user mailbox, not a shared or resource mailbox, unless you enable automapping.
• Folder existence: If the rule moves messages to a folder, that folder must already exist in the target mailbox. New-InboxRule does not create folders.

Steps to Deploy a Rule to a Single Mailbox

1. Connect to Exchange
   Open Exchange Online PowerShell or Exchange Management Shell. For Exchange Online, run: Connect-ExchangeOnline -UserPrincipalName admin@yourdomain.com. For on-premises, open the Exchange Management Shell as administrator.
2. Verify the target mailbox exists
   Run Get-Mailbox -Identity user@yourdomain.com | Format-List Name, RecipientTypeDetails to confirm the mailbox is a UserMailbox and not a shared or resource mailbox.
3. Check for an existing rule with the same name
   Run Get-InboxRule -Mailbox user@yourdomain.com -Name "Move Invoices to Archive". If the rule exists, remove it first: Remove-InboxRule -Mailbox user@yourdomain.com -Name "Move Invoices to Archive" -Confirm:$false.
4. Create the new inbox rule
   Run the New-InboxRule command with the required parameters. Example: New-InboxRule -Mailbox user@yourdomain.com -Name "Move Invoices to Archive" -From "invoices@company.com" -MoveToFolder "user@yourdomain.com:\Archive" -StopProcessing:$true. The -StopProcessing:$true parameter prevents other rules from running after this rule processes the message.
5. Test the rule
   Send a test email from the specified sender to the mailbox. Check that the message is moved to the target folder. To verify the rule properties, run Get-InboxRule -Mailbox user@yourdomain.com -Name "Move Invoices to Archive" | Format-List.

Deploying the Same Rule to Multiple Mailboxes

To apply a rule to many users, use a ForEach loop with Get-Mailbox. This example moves emails from a specific sender to an Archive folder for all users in the Sales department.

1. Get the list of target mailboxes
   Run $mailboxes = Get-Mailbox -Filter {Department -eq "Sales"} -ResultSize Unlimited. This stores all Sales department mailboxes in the $mailboxes variable.
2. Loop through each mailbox and create the rule
   Use this script:
   foreach ($mbx in $mailboxes) {
  Remove-InboxRule -Mailbox $mbx.Identity -Name "Move Invoices to Archive" -Confirm:$false -ErrorAction SilentlyContinue
  New-InboxRule -Mailbox $mbx.Identity -Name "Move Invoices to Archive" -From "invoices@company.com" -MoveToFolder ($mbx.Identity + ":\Archive") -StopProcessing:$true
}
   The Remove-InboxRule line uses -ErrorAction SilentlyContinue so the script does not stop if no existing rule is found.
3. Confirm the rules were created
   Run foreach ($mbx in $mailboxes) { Get-InboxRule -Mailbox $mbx.Identity -Name "Move Invoices to Archive" | Format-Table MailboxName, Name, Enabled }. This shows the mailbox name, rule name, and whether the rule is enabled.
4. Handle mailboxes without the target folder
   If a mailbox lacks the Archive folder, the command fails. To create the folder in each mailbox before applying the rule, run:
   foreach ($mbx in $mailboxes) {
  $folder = Get-MailboxFolder -Mailbox $mbx.Identity -FolderType Archive -ErrorAction SilentlyContinue
  if (-not $folder) { New-MailboxFolder -Mailbox $mbx.Identity -Name "Archive" -ParentPath "\" }
}
   Then run the rule creation loop again.

Using Conditions and Actions in Bulk Rules

New-InboxRule supports many parameters for conditions and actions. When deploying bulk rules, you can combine parameters to match specific scenarios.

Common condition parameters

• -From: Matches a specific sender email address or domain.
• -SubjectContainsWords: Matches messages where the subject contains any of the specified words.
• -BodyContainsWords: Matches messages where the body contains any of the specified words.
• -SentTo: Matches messages sent to a specific recipient address.
• -HasAttachment: Matches messages that have one or more attachments.

Common action parameters

• -MoveToFolder: Moves the message to a specified folder.
• -CopyToFolder: Copies the message to a specified folder without deleting the original.
• -ForwardTo: Forwards the message to a specified recipient.
• -DeleteMessage: Deletes the message without sending it to the Deleted Items folder.
• -MarkImportance: Sets the importance level to Low, Normal, or High.

Example: Create a rule that flags emails with attachments from external senders for all users in the IT department.
foreach ($mbx in $mailboxes) {
  New-InboxRule -Mailbox $mbx.Identity -Name "External Attachments" -From "@" -HasAttachment:$true -MarkImportance High -StopProcessing:$false
}

Common Deployment Mistakes and How to Avoid Them

Rule creation fails because the target folder does not exist

New-InboxRule does not create folders automatically. If a rule references a folder that is missing, the cmdlet returns an error. Always verify or create the folder before applying the rule. Use Get-MailboxFolder to check and New-MailboxFolder to create the folder as shown in the deployment steps above.

Duplicate rule names cause errors

Each mailbox can have only one rule with a given name. If you run New-InboxRule with the same name and the rule already exists, the cmdlet fails. Always call Remove-InboxRule with -Confirm:$false before creating a new rule with the same name. Alternatively, use a unique name per deployment by appending a timestamp, such as “Move Invoices to Archive 2025-03-15”.

The rule does not apply to messages already in the inbox

New-InboxRule creates rules that apply only to new messages arriving after the rule is enabled. Existing messages in the inbox are not affected. To move existing messages, use Search-Mailbox or the Move-MailboxFolder cmdlet, or ask users to manually apply the rule to their current inbox from Outlook.

Incorrect mailbox identity in the MoveToFolder parameter

The MoveToFolder parameter requires the full mailbox identity and folder path in the format "mailbox@domain.com:\Folder Name". If you use a variable like $mbx.Identity, ensure it contains the mailbox’s SMTP address or GUID. Using $mbx.PrimarySmtpAddress is safer than $mbx.Identity when the identity is an object ID.

New-InboxRule vs Other Rule Deployment Methods

Item	New-InboxRule (PowerShell)	Manual Rule Creation in Outlook
Deployment scope	Single mailbox or bulk via script	One mailbox at a time
Automation	Fully scriptable with loops and filters	No automation, requires GUI interaction
Rule storage	Server-side rule on Exchange or Exchange Online	Server-side rule, but created via Outlook
Folder creation	Must be done separately with New-MailboxFolder	Outlook creates folder automatically during rule setup
Error handling	Requires manual error checking in scripts	Outlook shows error dialogs during creation
Rollback	Use Remove-InboxRule in a loop	Delete rules manually in each mailbox

Use New-InboxRule when you need to deploy the same rule to many users quickly. Use manual creation only for one-off rules or when testing a new rule on a single mailbox before bulk deployment.

You can now use New-InboxRule to deploy inbox rules across user mailboxes in Exchange Online or Exchange Server. Start by testing the rule on a single mailbox, then use the ForEach loop with Get-Mailbox to apply it to a department or the entire organization. Always remove existing rules with the same name before creating new ones to avoid errors. For advanced scenarios, combine multiple conditions and actions in a single New-InboxRule command to handle complex email routing needs.