Use the Right Events for the Right Cases

One of the problems I often hear about from Outlook developers is that the sequencing of a particular event isn’t ideal for what they are trying to do. While sometimes this can be a hole in the Outlook platform, more often than not it’s because the developer isn’t using the best event for the scenario they are trying to build. Outlook often has multiple events that fire related to particular actions in the UI, and choosing the right event is important to ensure data consistency.

For example, recently I was helping a partner team who wanted to examine the contents of a meeting request when the user has actually sent the request. During this event, they would compare the state of the meeting in their system against the meeting that the user was sending, and fix up any inconsistencies in their database. The developer had found the AppointmentItem_Send event in the object model, and naturally presumed that was the right event to use. However, they started to notice that inconsistencies were occurring between items in Outlook and their database. Multiple-client issues aside, the problem is because of the event they used.

The Item_Send event fires when the user clicks the Send button on sendable items (Meeting requests, e-mail messages, etc). However, there are cases where the user can back out of sending the item after they click the send button. In this particular case, when a meeting is changed, the user is sometimes given a choice to send the updates to added/removed recipients, or to all recipients. If the user clicks cancel on this dialog, the send is canceled even though the Send event has fired.

To work around this issue, I instructed the developer to listen for the Application_ItemSend event instead. This event fires after the user has committed to sending the message and ensures that the recipients on the item reflect the state of the item after the inspector has been closed.

Likewise, there is a Close event on each of the item classes, as well as a Close event on the Inspector object. To ensure that you inspect the contents of the item after all edits have occurred, catching the Inspector_Close event will provide you with the best chance to see that information. After Item_Close has fired, there is still a chance the user will back out of the changes (for example, if they click No to save their changes).

There are times where using the Item_Close and Item_Send events are very useful though. For example, if you want to be able to cancel the event and prevent the item from being closed or sent, these events have a Cancel parameter which can be set to True to prevent the action from occurring. The more deterministic events on the Inspector and Application object are not cancelable, because that would affect their determinism.

Comments (8)

  1. sdsouza says:

    Hi Ryan,

    I have created a outlook Addin for OL2007 using VS2005 , in which the event is attached for item send  this.Application.ItemSend . When user creates a new mail and clicks on Send, it will be moved to new custom folder. I have attached a event to the folder to process the newly added mail.

    The event is added to the folder within my Addins code.

    This event gets fired some time and does not get  invoked due to the scope.

    Can you please let me know where I can write the code to attach the event to that folder so that the event gets fired whenever a new mail item is added to the custom folder?



  2. rgregg says:


    I assume you are using the Items.ItemAdd event to notice that new content has been added to the folder? This is the right event to use, but you need to hold on to a reference to the Items collection as long as you want to listen to the event. In managed code, if you release the reference to the Items object, the event can still fire until the object is actually garbage collected, and then it goes out of scope and the event no longer fires.

    You may also need to listen to the FolderChange event on the Folders collection (the parent of your Folder object) if you expect a large number of items to be added to a folder all at once.

  3. Scheevel says:

    Can I access these events in unmanaged code (VBA)?  Specifically the "FolderChange" event.

  4. rgregg says:

    Yes, you can. You can define an object using the WithEvents keyword in VBA, which enables you to catch events from the object.  For example:

    Dim WithEvents MyFolders As Folders

    Sub MyFolders_FolderChange(ByVal fldr as Folder)

    End Sub

  5. Scheevel says:

    Doh! The "FolderChange" event doesn’t tell me which "Item" changed.  I couldn’t find an event (for a user created folder) that passes me the changed "Item" object.

    I found a Ken Slovac’s suggested work-around to iterate thru a stored collection and find out what changed, but OUCH, that sounds like a lot of overhead.

    Instead I store the SystemTime at the start of the event, then use "Find" method to get the "Item(s)" whose "LastModificationTime" property matches my variable.  Unfortunately the time stamp is not to the millisecond, but for my purposes it works well.

    Thanks for making me aware of "FolderChange", let me know if there’s a better way to skin this cat.

  6. Scheevel says:

    The FolderChange event only tells me the folder, nothing about the MailItem that changed.  Is there another event that would tell me the item?  (Not that I could see).

    My work around; set a variable equal to the time at the start of the event, then iterate thru each MailItems looking at the "LastModificationTime" property.  (Can’t use the "Find" method, because the times are not exact) Converting the time-stamps to a double and rounding down to the 4th decimal consistently matches.

    Let me know if there’s a better way to skin this cat.  Thank you for your help!

  7. Aghosh says:

    I am developing an application that can update  an excel file saved in an outlook folder. So i try to open the outlook folder and trying to download the item and save to harddisk, edit and upload back, so now i have trouble in C# to download the excel file. how can i achieve this?

  8. romano_lever says:

    Hi, excelent post…

    Bus i’am having a problem that maibe you can help, is it possible in a MAilItem to read the binary of the embebed attachments without having to save it on the hard drive?