United States

Change

All Microsoft Sites

Help and Support

Article ID: 324568 - Last Review: March 29, 2007 - Revision: 5.4

Description of programming with Outlook rules

View products that this article applies to.

This article was previously published under Q324568

SUMMARY

This article provides developer-oriented information about how you can create custom solutions that manage e-mail messages. This article describes the following topics:

Overview of Rules
Existing Solution or Product
Rules Wizard "Run a script" Rules
Outlook Visual Basic for Applications Rules
Outlook COM Add-in Rules
Custom Actions for the Outlook Rules Wizard
Server-Side Rules Using Exchange Event Scripts and Sinks
Exchange SDK Rule Component

Back to the top

MORE INFORMATION

There is a variety of ways to implement or create solutions that handle incoming and outgoing e-mail. This article is a general overview of the options that are available.

Back to the top

Overview of Rules

With the Outlook Rules Wizard, you can manage both incoming and outgoing e-mail messages by defining instructions that should be applied to certain e-mail messages in certain scenarios.

NOTE: In earlier versions of Microsoft Outlook, this type functionality is provided by the Inbox Assistant. Although Outlook provides the Rules Wizard instead of the Inbox Assistant, the functionality that was provided by the Inbox Assistant is still used to process rules on Microsoft Exchange Server public folders.

For additional information about how to use the Rules Wizard, click the article numbers below to view the articles in the Microsoft Knowledge Base:

196212 (http://support.microsoft.com/kb/196212/EN-US/ ) OL2000: How to Use the Rules Wizard in Outlook 2000

291608 (http://support.microsoft.com/kb/291608/EN-US/ ) OL2002: How to Use the Rules Wizard in Outlook

When you develop solutions, it is important to understand that rules can run on the server or the client. All the Exchange Server-based rules are run first, and then Outlook client-based rules are run. If you are using an Exchange server, the rules are stored both locally on the client and also on the server. A rule is run on the server if it is possible; otherwise, the rule will be handled by Outlook on the client. The main disadvantage of client-side rules is that they can only run when Outlook is running online. Rules that cannot be completed on the server are marked "Client-only" in the Rules Wizard.

The following examples of Outlook rules can be run on the server:

Automatically reply to a message.
Move a message to another folder in the same store.
Copy a message to another folder in the same store.
Exchange Server public folder rules using the Folder Assistant.

The following examples of Outlook rules are run on the client:

Move a message to a folder in a PST file
"Custom Action" rules

You can use the Rules Wizard, and you can also use various technologies to create solutions that implement rules functionality. Some of these technologies integrate directly with the built-in Exchange Server and Outlook rules functionality. Others use independent custom code to create a solution that functions as the built-in rules features. All these types of solutions are discussed later in this article, but following is a summary of the technologies based on whether or not they apply to the server or client.

Client-side rules developer technologies:

Rules Wizard "Run a Script" rules
Outlook Visual Basic for Applications solutions
Outlook COM add-in solutions
Custom Actions for the Rules Wizard
Exchange SDK Rule Component (Rule.dll)

Server-side rules developer technologies:

Exchange Server 5.5 Scripting Agents
Exchange 2000 Server Event Sinks
Exchange SDK Rule Component (Rule.dll)

Back to the top

Existing Solution or Product

There is a variety of third-party products that have already been developed that are designed to provide functionality like rules. For more information about these products, visit one of the following Slipstick Web sites:

Slipstick.com (http://www.slipstick.com)

http://www.slipstick.com/addins/auto.htm (http://www.slipstick.com/addins/auto.htm)

Back to the top

Rules Wizard "Run a Script" Rules

Outlook 2002 Visual Basic for Applications can be used in the Rules Wizard by using the "Run a Script" option. The "script" in this case must be Outlook Visual Basic for Applications. You cannot use another programming language, or host the code in an Outlook COM add-in. This feature is not available in Outlook 2000.

For additional information about how to create a script for the Outlook Rules Wizard, click the following article number to view the article in the Microsoft Knowledge Base:

306108 (http://support.microsoft.com/kb/306108/ ) How to Create a Script for the Rules Wizard

One of the key advantages of this approach is that you can use the built-in functionality of the Rules Wizard to determine which messages are processed. However, Outlook Visual Basic for Applications is not designed to be deployed, so use this approach only for your own personal use. For additional information about limitations related to deploying Outlook Visual Basic for Applications, click the article number below to view the article in the Microsoft Knowledge Base:

290779 (http://support.microsoft.com/kb/290779/EN-US/ ) OL2002: Managing and Distributing Outlook VBA Projects

Back to the top

Outlook Visual Basic for Applications Rules

Instead of using the "Run a script" feature in the Rules Wizard, you can also create custom Visual Basic for Applications code in either Outlook 2000 or Outlook 2002 that functions as a rule. Typically, these solutions implement either the Item_Add event on the Inbox folder so that code runs whenever an item arrives in the Inbox, or the Application_ItemSend event so that code runs whenever an item is sent. An example of this approach is discussed in the following Knowledge Base articles:

292063 (http://support.microsoft.com/kb/292063/EN-US/ ) OL2002: How to Create a Custom Rule Using Visual Basic for Applications

235852 (http://support.microsoft.com/kb/235852/EN-US/ ) OL2000: How to Create a Custom Rule Using Visual Basic for Applications

Because Outlook Visual Basic for Applications code runs on the client, Outlook must be running for the code to run.

The following code sample is a rule that saves the attachments of a new e-mail message. Messages arriving with the subject "Test Att" and with attachments will have the attachments saved to the "C:\Test" folder with their file name. To implement this code, follow the steps in one of the Knowledge Base articles listed earlier in this article (Q292063 or Q235852), but substitute the following code instead of the code in those articles.

Dim WithEvents objInbox As Outlook.Items

Private Sub Application_Startup()
   Set objInbox = Session.GetDefaultFolder(olFolderInbox).Items
End Sub

Private Sub objInbox_ItemAdd(ByVal Item As Object)
   If Item.Class = olMail And Item.Subject = "Test Att" Then
      If Item.Attachments.Count > 0 Then
         Dim objAttachments As Outlook.Attachments
         Set objAttachments = Item.Attachments
         For Each objAttach In objAttachments
            ' Does not handle duplicate filename scenarios
            objAttach.SaveAsFile "C:\Test\" & objAttach.FileName
         Next
         Set objAttachments = Nothing
      End If
   End If
End Sub

Back to the top

Outlook COM Add-in Rules

You can create a custom rule solution by developing an Outlook COM add-in. COM add-in solutions function as Outlook Visual Basic for Applications code does, but can be deployed. For additional information about how to create a Visual Basic COM add-in, click the article numbers below to view the articles in the Microsoft Knowledge Base:

230225 (http://support.microsoft.com/kb/230225/EN-US/ ) OL2000: How to Create a COM Add-in for Outlook

291163 (http://support.microsoft.com/kb/291163/EN-US/ ) OL2002: How to Create a COM Add-in for Outlook

316983 (http://support.microsoft.com/kb/316983/EN-US/ ) OL: A Sample COM Add-in That Uses the Visual Basic 6.0 Add-in Template

238228 (http://support.microsoft.com/kb/238228/ ) How To Build an Office 2000 COM Add-In in Visual Basic

The following Outlook COM add-in sample code will move Reply messages to another folder. E-mail messages with a subject beginning with "RE:" are moved to the folder "Sent Mail Archive", which is on the same level as the Inbox. You can modify the strings "RE:" and "Sent Mail Archive" to customize this sample.

Dim WithEvents objOL As Outlook.Application

Private Sub AddinInstance_OnConnection(ByVal Application As Object, ByVal _
ConnectMode As AddInDesignerObjects.ext_ConnectMode, ByVal AddInInst As _
Object, custom() As Variant)
    Set objOL = Application
End Sub

Private Sub AddinInstance_OnDisconnection(ByVal RemoveMode As _
      AddInDesignerObjects.ext_DisconnectMode, custom() As Variant)
   Set objOL = Nothing
End Sub

Private Sub objOL_ItemSend(ByVal Item As Object, Cancel As Boolean)
   Dim objDefFolder As Outlook.MAPIFolder
   Dim objSentFolder As Outlook.MAPIFolder
    
   Set objInboxFolder = Session.GetDefaultFolder(olFolderInbox)
   Set objSentFolder = obInboxFolder.Parent.Folders("Sent Mail Archive")
    
   Dim strSubject As String
   Dim strLeft As String
    
   strSubject = Item.Subject
   strLeft = Left(strSubject, 3)
   If strLeft = "RE:" Then
      Item.SaveSentMessageFolder objSentFolder
   End If
    
   Set objInboxFolder = Nothing
   Set objSentFolder = Nothing
End Sub

Back to the top

Custom Actions for the Outlook Rules Wizard

Custom actions are developed by using C/C++ and must be installed on the computer running Outlook. Therefore, all custom actions are client-side rules. With custom actions, you can perform a specific action when a rule in the Rules Wizard is run. Outlook does not provide any custom actions, but many are available from third-party vendors. Documentation about developing a custom action is provided on MSDN. To view this documentation, visit the following Microsoft Web site:

http://msdn2.microsoft.com/en-us/library/ms981456.aspx (http://msdn2.microsoft.com/en-us/library/ms981456.aspx)

For additional information about custom actions, click the article number below to view the article in the Microsoft Knowledge Base:

196868 (http://support.microsoft.com/kb/196868/EN-US/ ) OL2000: Rules Wizard Custom Actions and Third Party Add-Ins

A sample Custom Action agent, named CRARUN, is available as part of the Exchange Server 5.5 SDK. For additional information about CRARUN, click the article number below to view the article in the Microsoft Knowledge Base:

151690 (http://support.microsoft.com/kb/151690/EN-US/ ) XCLN: What is the 'Custom' Rule Action For?

For more information about custom rules and actions, visit the following Slipstick Systems Web site:

All About Inbox Assistant and Rules Wizard Custom Actions (http://www.slipstick.com/emo/1997/up970804.htm#custom)

Back to the top

Server-Side Rules Using Exchange Event Scripts and Sinks

For scenarios where you require a custom rule to run on the server, you can use the Exchange 5.5 Scripting Agent or Exchange 2000 event sinks. These types of solutions are especially well suited for particular public folders or a limited number of mailboxes. For additional information, click the article numbers below to view the articles in the Microsoft Knowledge Base:

181036 (http://support.microsoft.com/kb/181036/EN-US/ ) INFO: Suitable Applications for Exchange Server Event Scripting

288156 (http://support.microsoft.com/kb/288156/ ) How To Create an Exchange 2000 Store Event Sink in Visual C++

Back to the top

Exchange SDK Rule Component

The Exchange 5.5 SDK includes a Rules Component (Rule.dll) that you can use to programmatically create rules in a folder. These rules are run on either the client or server, depending on the type of rule created. For additional information about using the Rules Component, click the following article number to view the article in the Microsoft Knowledge Base:

251125 (http://support.microsoft.com/kb/251125/ ) HOWTO: Use the Rule.dll Sample to Create an Inbox Rule from Visual Basic

NOTE: Rules that are created by using the Rules Component are not displayed in the Outlook user interface.

Microsoft provides third-party contact information to help you find technical support. This contact information may change without notice. Microsoft does not guarantee the accuracy of this third-party contact information.

The third-party products that are discussed in this article are manufactured by companies that are independent of Microsoft. Microsoft makes no warranty, implied or otherwise, regarding the performance or reliability of these products.

Back to the top