Inbox rules offer a wide array of activities that can be executed on an incoming message. They are an indispensable way to help users manage their email and are widely adopted. In addition to PowerShell, rules can be set up by the user both in Outlook and Outlook Web Access.

An example of where they can be useful could be pinning an important human resources message in the user inbox or in an emergency situation where you may want to send a text message across the organization.

The inbox-rules-related commands (Disable-InboxRule, Enable-InboxRule, Get-InboxRule, New-InboxRule, Remove-InboxRule, and Set-InboxRule) target individual accounts. If you need to roll out rules to the entire organization, you will need to write iterative scripts to update them one at a time.

In the following example, we set up a new rule to pin important messages for the test2 account. We then use Set-InboxRule to set StopProcessingRules so no additional rules are run after this rule executes:

New-InboxRule -Name "Pin Important" -Mailbox test2 -WithImportance "High" 
 -PinMessage $true

Name Enabled   Priority Rule Identity 
---- -------   -------- ---- -------- 
Pin  Important True     1    11719621876991918081

Set-InboxRule -Mailbox test2 -StopProcessingRules $true -Identity 11719621876991918081

Note the use of the identity parameter in Set-InboxRule to update the rule; using the -Name parameter in this command would update the Name value instead of it being used to find the rule:

Commands have a long list of possible filters for actions (BodyContainsWords, FlaggedForAction, From, FromAddressContainsWords, FromSubscription, HasAttachment, HasClassification, HeaderContainsWords, and MessageTypeMatches, to name a few) and just as many actions.

In the following script, we set up a new rule to send a text message to the user if we get an email from a specific email address. Text messages can be a powerful delivery system for important information as long as they are not overused:

New-InboxRule -Name 'Emergency SMS' -Mailbox admin1 -StopProcessingRules $true -From [email protected] -SendTextMessageNotificationTo '+3015555555'

Name          Enabled Priority RuleIdentity 
----          ------- -------- ------------ 
Emergency SMS True    1        4639937978293026817

New-InboxRule -Name 'Emergency SMS' -Mailbox test2 -StopProcessingRules $true -From [email protected] -SendTextMessageNotificationTo '+3015555555'

The operation on mailbox "test2" failed because it's out of the current user's write scope. The object 'test2' must be within the read scope before and after it's modified. Can't perform the save operation.

Note that the second command failed. This is due to a service account being used to run the command that does not have access to the text messaging settings of the target account. We will address permissions and this specific scenario later in the chapter. For the moment, we will say that text messaging settings cannot be set for another account through PowerShell.

In the next section, we will introduce Exchange Web Services (EWS), which will allow you to impersonate users and complete this and other scenarios.