Microsoft KB Archive/324568

= Description of programming with Outlook rules =

Article ID: 324568

Article Last Modified on 3/29/2007

-

APPLIES TO


 * Microsoft Outlook 2002 Standard Edition
 * Microsoft Outlook 2000 Standard Edition
 * Microsoft Exchange 2000 Server Standard Edition
 * Microsoft Exchange Server 5.5 Standard Edition

-



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 &quot;Run a script&quot; 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



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.

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 OL2000: How to Use the Rules Wizard in Outlook 2000

291608 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 &quot;Client-only&quot; 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
 * &quot;Custom Action&quot; 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 &quot;Run a Script&quot; 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)

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/addins/auto.htm

Rules Wizard &quot;Run a Script&quot; Rules
Outlook 2002 Visual Basic for Applications can be used in the Rules Wizard by using the &quot;Run a Script&quot; option. The &quot;script&quot; 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 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 OL2002: Managing and Distributing Outlook VBA Projects

Outlook Visual Basic for Applications Rules
Instead of using the &quot;Run a script&quot; 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 OL2002: How to Create a Custom Rule Using Visual Basic for Applications

235852 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 &quot;Test Att&quot; and with attachments will have the attachments saved to the &quot;C:\Test&quot; 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 = &quot;Test Att&quot; 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 &quot;C:\Test\&quot; & objAttach.FileName Next Set objAttachments = Nothing End If  End If End Sub

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 OL2000: How to Create a COM Add-in for Outlook

291163 OL2002: How to Create a COM Add-in for Outlook

316983 OL: A Sample COM Add-in That Uses the Visual Basic 6.0 Add-in Template

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 &quot;RE:&quot; are moved to the folder &quot;Sent Mail Archive&quot;, which is on the same level as the Inbox. You can modify the strings &quot;RE:&quot; and &quot;Sent Mail Archive&quot; 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(&quot;Sent Mail Archive&quot;) Dim strSubject As String Dim strLeft As String strSubject = Item.Subject strLeft = Left(strSubject, 3) If strLeft = &quot;RE:&quot; Then Item.SaveSentMessageFolder objSentFolder End If  Set objInboxFolder = Nothing Set objSentFolder = Nothing End Sub

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

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

196868 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 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

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 INFO: Suitable Applications for Exchange Server Event Scripting

288156 How To Create an Exchange 2000 Store Event Sink in Visual C++

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 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.

Additional query words: OutSol OutSol97 OutSol98 OutSol2000 OutSol2002

Keywords: kbwizard kbscript kbvba kbaddin kbprogramming kbhowto KB324568

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.