How to manage inbox rules in Microsoft 365 with PowerShell

Inbox rules in Office 365 (or Microsoft 365, if you like the newer name better) help users and admins make Outlook a better place. They can be employed to fight distractions, get things organized, block unwanted correspondence or automatically forward selected emails. With the never-ending onslaught of information that flows into Outlook, they are invaluable. In this article, I’ll show you how to work with Office 365 inbox rules using PowerShell.

Manage inbox rules in Office 365 with PowerShell

Server-side vs client-side inbox rules

Before we dive into inbox rule management, there’s one thing that needs explaining. There are two kinds of inbox rules – server-side and client-side (client-only).

Server-side inbox rules are executed on server level. It means that they are applied whether Outlook is turned on or off. They are similar to mail flow rules, but there are fewer conditions, exceptions and actions to choose from. Also, mail-flow rules are applied while an email is in transit and are not set up on a per-mailbox basis. Although these rules are more versatile, there are some things they cannot do, and that’s where inbox rules come in handy.

Client-side or client-only inbox rules are exclusive to Outlook for Windows. They were also available in Outlook for Mac, but since the introduction of “new Outlook for Mac” in October 2020, they have been retired. While basic information about these rules is stored online in the mailbox on the Exchange Server, these rules are executed by the email client (your “desktop Outlook”). So, if you receive a new email in your mailbox while Outlook is turned off, client-side inbox rules will not be executed.

While in most cases this difference has only minor impact on the user, it’s critical from the admin’s perspective. Why? Because while you can list every client-side rule of every user using PowerShell, you can’t create a client-only rule this way. What’s more, using some PowerShell cmdlets will remove disabled client-side rules and outbound rules will also be removed. These “destructive cmdlets” are listed below:

New-InboxRule,
Set-InboxRule,
Remove-InboxRule,
Enable-InboxRule,
Disable-InboxRule

Using one of these cmdlets might break some carefully crafted user-made Outlook rules. The only safe cmdlet is Get-InboxRule, which lets you see all rules that apply to a given mailbox.

The tricky part is that it can be either a rule’s condition or the action, which makes a rule client-side. As you will see, in some cases finding out if a rule is client-only or server-side, might be tricky.

Check the rule’s type

When using Outlook or Outlook on the web, finding a rule’s type is as easy as it gets. Outlook for Windows adds this information (client-only) to every such rule:

Outlook on the web shows quite a verbose warning:

client-only inbox rule in Outlook on the web

Finally, this Microsoft’s page lists conditions and actions which make a rule client-only. Keep in mind, though, that the following conditions:

with specific words in the subject,
marked as importance,
marked as sensitivity,
flagged for action,
with specific words in the body/message header/recipient’s address/sender’s address,

and actions:

assign it to the category,
mark as read

can be applied by using certain parameters to the New-InboxRule cmdlet which is used to create a server-side rule.

Tests show that if you create an inbox rule to mark emails as read in Outlook, it will be client-side. But if you create the same inbox rule in Microsoft 365 using PowerShell, it will be server-side. Hope that clears things up.

Export Microsoft 365 inbox rules with PowerShell

It might be useful to export Microsoft 365 inbox rules of your users in at least two scenarios:

If you decide to manage these rules using PowerShell (which might delete some of the user-defined rules, as mentioned before).
If you ever need to troubleshoot inbox rules for your users.

You can export inbox rules manually to an RWZ file, using Rules > Manage Rules & Alerts > Options in Outlook. The upside is that these rules can be easily imported back into Outlook, should anything go wrong. The downside – an admin would need to either log into each mailbox and perform the export manually or outsource this task to the users.

Another thing you could do is export inbox rules with PowerShell. The main advantage is that you can do it in a matter of seconds (not counting the time PowerShell needs to execute the task). The nasty disadvantages are that you won’t get the whole picture about the client-side rules and there’s no easy-to-use import feature. However, when troubleshooting inbox rules for a user, having limited historical data and absolutely no data makes a huge difference.

The following short script exports a list of all inbox rules from every mailbox in the organization. Results are exported to separate CSV files, one for each mailbox:

$mailboxes = get-mailbox
foreach ($mailbox in $mailboxes) {get-InboxRule -Mailbox $mailbox.UserPrincipalName | export-csv "C:\$mailbox.csv"}

Learn more about inbox rule usage

Get-InboxRule provides a way to see how many rules a company uses. You can, for example, check how many rules a user has configured:

$mailboxes = Get-Mailbox
foreach ($mailbox in $mailboxes) {
Write-Output $mailbox.id,((Get-InboxRule -Mailbox $mailbox.Id)|Measure-Object|select count)
}

From the output you may learn that:

it’s completely safe to manage inbox rules in your Microsoft 365 tenant, because most users don’t have any rules configured, or
touching some rules with PowerShell may backfire for some mailboxes, because they have hundreds of rules configured.

You can also look for certain rules, for example inbox rules which are used to forward emails:

foreach ($mailbox in $mailboxes) {
Get-InboxRule -Mailbox $mailbox.UserPrincipalName | where ForwardTo;
Get-InboxRule -Mailbox $mailbox.UserPrincipalName | where ForwardAsAttachmentTo
}

If the script returns any rules, you can use Get-InboxRule to find out more:

Get-InboxRule -Identity <InboxRuleIdParameter> | FL

Side note: This is only an example. By default, creating a forwarding rule triggers a low-severity security alert. You can toggle this setting in the Microsoft 365 Defender admin center. There are also multiple ways to prevent auto-forwarding in Exchange Online.

Create a new inbox rule for everyone

One of the greatest advantages of managing Outlook rules with PowerShell is that you can quickly create a set of rules for every mailbox in your organization without any involvement of the users. Take a look at this example:

Your communications department has concluded that notifications cripple productivity (which they do). A constant barrage of notifications can de-focus most people beyond help. One of the ways to tackle this is to automatically mark all incoming emails as read. If paired with the Inbox 0 workflow, this is an effective way of preventing users from checking their inbox every 15 seconds, whenever low priority emails reach them. This can also help the users become more self-aware and break the habit of peeking into their mailbox ever so often.

Your task is to introduce such rule for all mailboxes in the company. You can do it with a few simple lines of PowerShell code. To make things more interesting, let’s add an exception – an email should not be automatically marked as read if the message comes from the CEO, or if it has High Importance set. The code is as follows:

$mailboxes = get-mailbox
foreach ($mailbox in $mailboxes) {
New-InboxRule -Mailbox $mailbox.UserPrincipalName -Name "Mark all as read" -MarkAsRead $true -ExceptIfFrom [email protected] -ExceptIfWithImportance High
}

For more information on inbox rules, take a look at Managing users’ Outlook rules from Exchange Management Shell. Although that article focuses on Outlook rules in the on-premises Exchange, the insights there apply to Microsoft 365 as well.