Handling NewMail, NewMailEx and ItemAdd Outlook events in .NET

Sometimes you need to process incoming e-mails and meeting requests in order to retrieve sender data for your CRM, to save attachments to your Document Management System (DMS), to process automated e-mails, or to convert selected incoming messages to plain text. Whenever you need to track incoming e-mails, you face the following Outlook events: NewMail, NewMailEx, and ItemAdd.

In a minute I will tell you how to use these events, uncover their drawbacks, and show how to use the MAPI Store Accessor to bypass negative sides of these events in .NET.

NewMail

Notwithstanding its name, this event fires at a few minute intervals. It ignores any incoming items which arrived shortly after a previous NewMail event. Another limitation makes the NewMail event almost useless if more than 16 items arrive at once, the event will not fire at all!

NewMailEx

This event was introduced in Outlook 2003. It improves monitoring of incoming messages by providing access to EntryIDs of newly arrived e-mails. EntryIDs are separated with commas in a string parameter of the NewMailEx event. You can easily get any item using its EntryID:

NameSpace.GetItemFromID(EntryID)

Well, this method has restrictions of its own. Say, if more than 1000 items come at once, some of them may be missing. That is, you can’t rely on the NewMailEx event alone. You may want to regularly check for unprocessed messages, say by using a timer.

ItemAdd

You can also use the ItemAdd event of the Items collection of Outlook folder class (MAPIFolder in Outlook 2000-2007, Folder in Outlook 2007). This is especially useful when you need to check new mails in some other folder, say, another user’s Inbox. However, note that ItemAdd will not fire if more than 16 items are added at the same time. This restriction has the same root as that of the NewMail event. For instance, Microsoft writes that “this is due to Microsoft Exchange Server and MAPI using different methods when moving large amounts of data. Outlook does not take this into account and therefore the event fails to fire in those cases.”. They also suggest periodically checking the number of items in the folder to see if there are new items.

MAPI

MAPI enables you to bridge the gap between Outlook events and developers demands. You can use our MAPI Store Accessor which connects to the MAPI subsystem and subscribes to selected events at the MAPI level. As a result, you will get all needed notifications such as NewMail, ObjectModified, ObjectDeleted, etc. No restrictions of mentioned above. But, alas, in this case there is the other side of the coin, too. If you use Exchange Server in a profile you may encounter situations in which you don’t get a needed event notification such as OnNewMail. The reasons may be:

• The Mapi Store Accessor connects to the MAPI subsystem after the first synchronization between Outlook and Exchange (i.e. when Outlook loads). That is, you will not get notifications for all e-mails that were received before the MAPI Accessor initialize subroutine. To solve this problem you can try to use Exchange Client Extensions. You can read more in an article in MSDN.
• You close Outlook before event notification arrived and that is why you do not get it anymore. To resolve this issue you have to track all items and check by timer for new items. For instance, you can use ReceivedTime or set user properties on arrived emails and is this way you can recognize old and new ones. Certainly you can choose your own way of tracking new emails.

My experience shows that for Exchange server profiles, an event notification may delay for an on an arbitrary period. Some developers mistakenly reported that event notification didn’t work with Exchange server. In fact, they missed event notifications when closing Outlook immediately after the event had occurred.

Eugene Astafiev
Add-in Express Team