Understanding Events in Outlook

  • Article

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

There are two classes of events in Outlook, and you work with each class differently. The first class represents item-level events that are associated with a particular Outlook item. For example, an Outlook MailItem object has events such as Open, Close, Forward, and Send. As in previous versions of Outlook, you use VBScript code within the item itself to handle these item-level events.

The second class of events supported in Outlook represents application-level events. Because these events are associated with the application itself, or with top-level objects within the application, such as folders or the Outlook Bar, you can use VBA code to handle these events.

Application-Level Events

When you create a new VBA project in Word or Excel, the project contains, by default, a class module bound to the application's current document. For example, Word creates a module for the ThisDocument object and Excel creates a module for the ThisWorkbook object. In Outlook, because you use VBA to work with the application, the VBA project contains a class module called ThisOutlookSession, which is pre-bound to the Outlook Application object. As a result, all application-level events are available to you in the Visual Basic Editor's Procedures drop-down list when you click the Application object in the Object drop-down list.

There are six events associated with the Application object that you can use to run custom VBA procedures. For example, you could use the Startup event to call custom procedures to customize the Outlook workspace or to create or display custom command bars or command bar controls. You could use the NewMail event procedure to call custom procedures that implement your own rules for handling incoming mail. These events are somewhat self-explanatory, and you can get complete documentation for each event by searching the Microsoft Outlook Visual Basic Reference Help index for the name of the event.

Other Outlook Events

Working with the event procedures exposed by other Outlook objects is identical to creating event procedures in the other Office applications and requires a few more steps than are required when you are working with Application object events. First, you must declare an object variable by using the WithEvents keyword in the ThisOutlookSession module (or in another class module) for each object you want to work with. Second, you must add the VBA code to the event procedure that you want to run when the event occurs. Finally, you must initialize the object variables that you have created.

For example, the following VBA code illustrates how to create an object variable that represents the Outlook Bar in the ThisOutlookSession module:

Dim WithEvents obpOutlookBar As Outlook.OutlookBarPane

Once you declare an object variable as shown in the previous example, the variable name appears in the Object drop-down list in the class module's Code window. When you select this variable from the Object list, you can select the object's available event procedures by using the Procedure drop-down list. For example, the OutlookBarPane object shown earlier exposes the BeforeGroupSwitch and BeforeNavigate events.

Private Sub opbOutlookBar_BeforeNavigate(ByVal Shortcut As OutlookBarShortcut, _
      Cancel As Boolean)
   If Shortcut.Name <> "Inbox" Then
      Msgbox "Sorry, you only have permission to access the Inbox."
      Cancel = True
   End If
End Sub

Now you need to initialize the object variable. You can do this in two places: in the Application object's Startup event procedure, so that the variable is always available, or in a custom procedure you create for the purpose of initializing object variables. The following code shows how to initialize the object variable by using the Startup event procedure:

Private Sub Application_Startup()
   Set opbOutlookBar = Application.ActiveExplorer.Panes("OutlookBar")
End Sub

To determine how to instantiate an object variable, search the Microsoft Outlook Visual Basic Reference Help index for the name of the object you want to work with. For example, the Help topic for the OutlookBarPane object shows that the object is a member of the Panes collection and also that you use the string "OutlookBar" to identify the object within the collection.

You can get more information about the objects, methods, and properties in the Outlook object model by using Microsoft Outlook Visual Basic Reference Help in the C:\Program Files\Microsoft Office\Office\1033\Vbaoutl9.chm file.

Note   The path to the Vbaoutl9.chm Help file reflects the language ID folder (1033) for U.S. English language support in Office. The language ID folder below C:\Program Files\Microsoft Office\Office differs for each language.