Hey, Scripting Guy! How Can I Tell Which Outlook Rules I Have Created?

Bookmark and Share 


Hey, Scripting Guy! Question

Hey, Scripting Guy! I don’t know about you, but it seems that I am getting overwhelmed at work with e-mail. In the old days, e-mail was not much of a problem and it was a great way to communicate. Today, I get so much e-mail that it would actually take all day for me to read it. The problem is that some of it is actually important. I have created a bunch of rules that will delete certain e-mail messages, move other messages to certain folders, and play a specific sound if I get an e-mail message from my boss. Now the problem is that I have too many rules, and some of them actually conflict with one another.

I need a good way to visualize which rules I have so that I can determine if I still need the rule. Could you write a Windows PowerShell script that would tell me which Microsoft Outlook inbox rules I have created?

-- PC


Hey, Scripting Guy! AnswerHello PC,

Microsoft Scripting Guy Ed Wilson here. I spent the weekend out in my woodworking shop making a table for my mother-in-law. It is a simple little table, but it took an inordinate amount of time to hand cut the mortise and tenon joints for the apron. The nice thing about hand cutting woodworking joints is that it is quiet. I can listen to classical music on my Zune HD because I have a docking station in my wood shop, and it is very peaceful. There is something relaxing about the sound of a sharp plane as it scrapes across the wood as it takes .001 off an inch of the side of a tenon for a precise fit.

I get a similarly peaceful feeling from a finely crafted Microsoft Office Outlook rule that deletes thousands of inane e-mails from my inbox. As with fitting a hand-cut mortise and tenon joint, one does not want to remove too much—just exactly enough. I imagine that FDISK would solve many of one’s e-mail problems, but that would be akin to using a chain saw on my mother-in-law’s table. It would remove Office Outlook, Microsoft Windows, and all of my data along with it.

To get a precisely fitting joint, I make a couple passes with my plane, and then I test fit the leg. To get Outlook inbox rules that are a precise fit for your needs, you create the rule and inspect the results. Having a list of inbox rules is the first step in the right direction.

The complete ListOutLookRules.ps1 script is seen here.


#Requires -version 2.0
Add-Type -AssemblyName microsoft.office.interop.outlook
$olFolders = "Microsoft.Office.Interop.Outlook.OlDefaultFolders" -as [type]
$outlook = New-Object -ComObject outlook.application
$namespace  = $Outlook.GetNameSpace("mapi")
$folder = $namespace.getDefaultFolder($olFolders::olFolderInbox)
$rules = $outlook.session.DefaultStore.GetRules()
$rules |
Sort-Object -Property ExecutionOrder |
Format-Table -Property Name, ExecutionOrder, Enabled, isLocalRule -AutoSize

The ListOutLookRules.ps1 script will display all rules that you have created in Microsoft Outlook. The Outlook Rules and Alerts Wizard, seen in the following image, will also display the rules you have created:

Image of Outlook Rules and Alerts Wizard


The first thing that is done in the ListOutLookRules.ps1 script is adding the microsoft.office.interop.outlook assembly to the current Windows PowerShell session. Because the Add-Type cmdlet is used to do this and the Add-Type cmdlet only exists on Windows PowerShell 2.0, the #Requires –version 2.0 tag is used to prevent the script from running on Windows PowerShell 1.0 machines. For more information about using the Add-Type cmdlet, see yesterday’s Hey, Scripting Guy! article.

The Add-Type command is seen here:

#Requires -version 2.0
Add-Type -AssemblyName microsoft.office.interop.outlook

Next, the OlDefaultFolders enumeration is created. The OlDefaultFolders enumeration will be used with the GetDefaultFolder method to make a connection to the user’s inbox. The enumeration is stored in the $olFolders variable, as shown here:

$olFolders = "Microsoft.Office.Interop.Outlook.OlDefaultFolders" -as [type]

It is now time to create the Outlook.Application COM object. To do this use the New-Object cmdlet with the –ComObject parameter. The resulting application object is stored in the $outlook variable, as seen here:

$outlook = New-Object -ComObject Outlook.Application

You will also need a namespace object. To obtain a namespace object, use the GetNameSpace method from the Outlook.Application COM object. The resulting namespace object is stored in the $namespace variable, as shown here:

$namespace  = $Outlook.GetNameSpace("mapi")

To connect to the mailbox, you use the GetDefaultFolder method from the namespace object. The GetDefaultFolder method receives the enumeration that was previously stored in the $olFolders variable. The resulting folder object is stored in the $folder variable, as seen here:

$folder = $namespace.getDefaultFolder($olFolders::olFolderInbox)

After the application object, the namespace, and the connection to the mailbox have been established, you can call the GetRules method to return the mailbox rules. The Session property from the Application object returns a NameSpace object that represents the current session. The NameSpace object has the DefaultStore property that returns a Store object that represents the default store for the Outlook profile. It is the store object that has the GetRules method. The GetRules method returns a Rules Object that is made up of a collection of Rule objects that are present in the current session. The use of the GetRules method to return a collection of Outlook rule objects is seen here.

$rules = $outlook.session.DefaultStore.GetRules()

Now that you have a collection of rules, you can work with them by using standard Windows PowerShell cmdlets. In the ListOutLookRules.ps1 script, they are sent along the Windows PowerShell pipeline as seen here:

$rules |

The Sort-Object cmdlet is used to sort the rules by the ExecutionOrder property. The ExecutionOrder property is used by Microsoft Outlook to determine the order in which the rules will be executed. The Sort-Object cmdlet is seen here:

Sort-Object -Property ExecutionOrder |

Finally, the Format-Table cmdlet is used to generate a table that displays the ExecutionOrder, whether the rule is enabled or local, and the name of the rule. The –autosize parameter reduces white space between the columns in the table. The Format-Table command is shown here:

Format-Table -Property Name, ExecutionOrder, Enabled, isLocalRule –AutoSize

When the script is run inside the Windows PowerShell 2.0 ISE, the results seen in the following image are displayed on my computer:

Image of results in Windows PowerShell ISE of running script


PC, that is all there is to retrieving a list of your Outlook rules. Microsoft Outlook Week will continue tomorrow.

If you want to know exactly what we will be looking at tomorrow, follow us on Twitter or Facebook. If you have any questions, send e-mail to us at scripter@microsoft.com or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.


Ed Wilson and Craig Liebendorfer, Scripting Guys


Comments (3)

  1. VB script for rules? says:

    Hey, i don't know how to build a code in VB script to pull all the rules being used in my outlook 2007? pls help me with that.

  2. Josh says:

    Hey, I'm experimenting with your script to modify some rules for a mailbox.  I'm new to comobjects so I don't fully understand them.  When I run your script I want to see the conditions, actions, and exceptions for each rule but the data under each only shows "System.__ComObject".  How do I grab that data?

  3. Justin Morse says:

    How do I add new ones and remove them?

    Since there is a limit to how many rules can be added, I’d like to have a script that does this:

    1. Adds Rule group 1
    2. Executes them
    3. Removes Rule group 1
    4. Adds Rule group 2
    5. Executes them
    6. Removes Rule group 2

    Is this possible?

Skip to main content