Flagging Incoming Items

In the January 2000 Outlook VBA on Demand, I told you about application-level events that let you write code to respond to occurrences within Microsoft Outlook. Specifically, I described how to write code to react to the presence of a new item in a folder. If you build a procedure to respond to new items in the Inbox folder, you're essentially writing a substitute or supplement for Outlook's Rules Wizard. (Remember that VBA code runs only when Outlook is running. You can't use VBA code to replace server-side rules that run when Outlook is offline.) In this installment, I show you how to duplicate the Rules Wizard's with specific words in the body condition and how to add a message flag to an incoming item.

To duplicate Rules Wizard conditions, your code checks the properties of incoming messages for specific information. Which properties might you want your code to check? An easy way to learn about message properties is to look in VBA's Object Browser.

1. In the VBA window, select View, Object Browser, or press F2.
2. When the Object Browser appears, as Screen 1 shows, choose Outlook in the top drop-down list (which displays All Libraries by default).
3. In the Classes list, scroll down and select MailItem. (MailItem is the Outlook message's official object class.) In the right pane, you'll see the members of MailItem, beginning with the Actions property.
4. If you want to see all the message properties grouped together, right-click in the Members pane and click Group Members on the pop-up menu. The Object Browser displays all the properties together, followed by the methods for the MailItem object and its events. (Methods are actions that you can perform on a MailItem.)

Table 1 maps Rules Wizard conditions to an Outlook MailItem object's properties. Notice that the relevant property isn't always obvious. For example, you might expect the Flagged for action rule to use the Actions property. Instead of the Actions property, the rule uses the FlagStatus property (if you decide to check for any message flag) or the FlagRequest property (if you decide to check for a specific flag). Until you become fluent in the language of the Outlook Object Model, you can refer to the properties' Help topics for information. To display a property's Help topic, simply select the property in the Object Browser and press F1.

Suppose you want to search an item's text for a particular word or phrase. Listing 1 shows an event handler that works on the Inbox folder to detect the ItemAdd event on the folder's Item collection. (Remember that this procedure requires the WithEvents declarations and instantiation procedures that I described in the January 2000 column.) In Listing 1, the subroutine uses the Instr() function to search the body of the item (i.e., the message's text) for the string "ASAP": If the Instr() expression finds "ASAP", the subroutine sets a message flag on the item with a due date 5 days from that moment.

Instr() is a function that lets you search inside any text (i.e., the first argument) for a word or phrase (i.e., the second argument). Instr() returns an integer value based on whether the function finds the text it's searching for. If the Instr() function fails to find the text, the result is zero. If the function finds the text, the result is the position of the search string ("ASAP", in this example) inside the text block that Instr() is searching—an integer value that is always greater than zero.

You need to know a couple of other facts about the code in Listing 1. First, the FlagRequest property isn't limited to the choices you see on the drop-down list in Outlook's Message Flag dialog box. You can flag a message with any text. Second, the expression that sets the value of the FlagDueBy property—Now() + 5—uses the special Now() function. Now() returns the current date and time. Because of the way Outlook stores dates, to add 5 days to the current date and time, you simply add 5 to Now().

Now that you know how to use Instr() to search inside text and how to set a message flag, you can build variations that also search the Subject property. In my next column, I'll continue this exploration of Inbox item processing. I'll show you how to create a rule that checks for an empty To or From field—something you might see on junkmail items, but something that the Rules Wizard can't detect with any of its conditions.