New ‘Sweep’ PowerShell Cmdlets

Over the weekend, Microsoft quietly added a new set of PowerShell cmdlets to their Exchange Online PowerShell module. These cmdlets are designed to complement a feature that was included in Office 365’s Outlook on the Web client. The feature the PowerShell cmdlets affect is called ‘Sweep’ which provides web users of Exchange Online a way to help keep their Inbox clear and more manageable. Using the web client we can see the option is available in the toolbar above any emails present:

If you click on the sweep button, you have four options that appear as well as an option to check existing rules:


Clicking on the ‘View Rules’ option, we see what rules are already in place:

The New PowerShell Functionality
The new cmdlets available are as follows:

Disable-SweepRule
Enable-SweepRule
Get-DataRetentionReport
Get-SweepRule
New-SweepRule
Remove-SweepRule
Set-SweepRule

So what do these rules allow us to do? Let’s start with the ‘New-SweepRule’
Start out with Get-Help New-SweepRule -Full to get an idea of the cmdlets syntax and options to use:

When running Get-Help Enable-SweepRule it looks like Microsoft has not added any information quiet yet. In other words you are flying blind on this for now:

In order to figure this one out, we will have to start with the parameters which are requires according to the Help results:

Well, that isn’t a lot to go on. ‘Provider’ is not an obvious parameter whereas ‘Name’ is probably the name of the new sweep rule we are creating. With a bit of experimentation you should be able to create a rule. The key is to supply a mailbox to apply the rule to, a condition (like Sender) and how often messages are swept (10 Days 30 Days or all messages). Here is a sample working rule:

New-SweepRule -Name "Test Sweep" -KeepForDays 30 -mailbox damian0365@tenant.onmicrosoft.com -provider sweep -sender damian@practicalpowershell.com

This provides some feedback:

** Note ** I do not know what a valid provider is at this time. This is something I just put in there for testing.
Get-SweepRule -Mailbox damian0365@tenant.onmicrosoft.com | fl will display the new rule:

Reviewing the results from the Get-SweepRule, we can see some that the rule is set to sweep messages older than 30 days from the Inbox and place them in the Deleted Items folder. The sender in this case is part of the tenant and if we choose an external email address, that would be revealed as [SMTP:name@domain.com].
Removing a Sweep Rule
Removing a rule requires two pieces of information, the mailbox the rule is applied to as well as an Identity. The ‘Identity’ is NOT the identity listed in the rule, but is actually the ‘RuleID’ property of the rule. In fact, if you specify the Identity value and the mailbox name at the same time, because you will get an error like this:

However, if you use the mailbox name (like Primary SMTP address) and the RuleID value of the Sweep Rule to remove, it will ask if you truly wish to remove that rule:

Enter ‘Y’ and the rule is remove.
Disable-SweepRule and Enable-SweepRule work hand in hand. In case you need to disable an active Sweep rule, that can be accomplished with the Disable-SweepRule like so:

Disable-SweepRule -Mailbox <mailbox primary SMTP> -Identity <RuleID>

And if you wish to enable a rule that was disabled, just use the Enable-SweepRule like this:

Enable-SweepRule -Mailbox <mailbox primary SMTP> -Identity <RuleID>

At the moment there is very little documentation on how to create the rules, but these new cmdlets should provide administrators a way to provide Sweep Rules to their end user’s.
One Issue Noticed (So Far)
While experimenting with the new cmdlets I noticed that I was able to create two rules with the same name for the same mailbox. This could b confusing if you are not careful. The Sweep Rules get different Identity properties, but the Name of the rules are the same:

Not sure if there are any side-effects to do this, just be aware it is possible to do so.
Additional Note
After writing this article I decided to test one thing on a test account. I created a Sweep Rule for a test mailbox and I was able to deleted it as that user. Examining the cmdlets help, I did not see a way to block the end user from deleting the rule. Another item to be aware of.