Outlook Item events explained: C#, VB.NET

Spring has finally sprung down here and I thought today would be a great day to dive into the Outlook Item Events Class provided by Add-in Express and have a closer look at what each event in this class does. For this example I’ll be using Add-in Express for Office and .Net.

To get started, create a new COM Add-in project in Microsoft Visual Studio 2010.

In the first prompt of the New Microsoft Office COM Add-in project wizard, select your programming language and the Minimum Office version you would like to support. In this example it will be Visual C# and Microsoft Office 2007.

The Outlook ItemEvents class is only available for Outlook, so select only Microsoft Outlook in the Supported Applications list.

Complete the wizard and add a new Outlook Item Events Class to your project by selecting Add New Item… from the Visual Studio Project menu. You can find the template under Add-in Express Items > Outlook.

Before we can respond to the events in the class, we need to do some work in the AddinModule class. Switch to the AddinModule.cs code view and declare the OutlookItemsEventsClass:

private OutlookItemEventsClass outlookItemEvents = null;

Next open the AddinModule.cs designer and double-click in the AddinStartupComplete event in die property grid, this will generate an event handler. Add the following code to the new event handler:

private void AddinModule_AddinStartupComplete(object sender, EventArgs e)
{
	outlookItemEvents = new OutlookItemEventsClass(this);
}

Switch back to the AddinModule.cs designer and add a new Microsoft Outlook events component.

Select the newly added Outlook events component and double-click its InspectorActivate event in the property grid to generate an event handler. Add the following code:

C# code example

private void adxOutlookEvents_InspectorActivate(object sender,
	object inspector, string folderName)
{
    if (canConnect)
    {
        Outlook._Inspector olInsp = (Outlook._Inspector)inspector;
        object item = olInsp.CurrentItem;
 
        if (item is Outlook._MailItem)
        {
            outlookItemEvents.ConnectTo(item, true);
        }
    }
}

We need to add some more code in order to support the item connection regardless of whether the item is open/active or selected in an active explorer. (Thanks to Sergey for the code review and suggestions!)

Add the following method to the AddinModule class:

private void ConnectToSelectedItem(object explorer)
{
    Outlook.Selection sel = null;
 
    try
    {
        Outlook._Explorer expl = explorer as Outlook._Explorer;
        sel = expl.Selection;
        if (sel.Count == 1)
        {
            object item = sel[1];
            if (item is Outlook._MailItem)
                outlookItemEvents.ConnectTo(item, true);
            else
                Marshal.ReleaseComObject(item);
        }
    }
    finally
    {
        if (sel != null)
            Marshal.ReleaseComObject(sel);
    }
}

Next, we need to wire up the ConnectToSelectedItem method. To do this, add an event handler for ExplorerActivate and ExplorerSelectionChange:

private void adxOutlookEvents_ExplorerActivate(object sender, object explorer)
{
    ConnectToSelectedItem(explorer);
}

Add some code to check whether we can connect to items in an explorer, do this in ExplorerClose:

private void adxOutlookEvents_ExplorerClose(object sender, object explorer)
{
    int count = 0;
    Outlook._Explorers expls = null;
 
    try
    {
        expls = OutlookApp.Explorers;
        count = expls.Count;
    }
    catch
    {
    }
    finally
    {
        if (expls != null)
            Marshal.ReleaseComObject(expls);
    }
 
    if (count == 0)
        canConnect = false;
}

We need to clean up after ourselves by properly disposing of the ItemEvents object, to do this add event handlers for ItemSend, InspectorClose and AddinBeginShutdown:

private void adxOutlookEvents_ItemSend(object sender, ADXOlItemSendEventArgs e)
{
    if (outlookItemEvents != null)
        outlookItemEvents.RemoveConnection();
}

Now that we’ve hooked up the necessary code in order to raise the events, switch to the OutlookItemEventsClass and let's look at the events we can respond to.

ProcessAttachmentAdd

This event fires when you attach a file to an Outlook item i.e. MailItem, TaskItem , ContactItem and AppointmentItem. A reference to the attachment is passed into the method and you can get more information about it by casting it to an Outlook.Attachment object as illustrated in the example below:

C# code example

public override void ProcessAttachmentAdd(object attachment)
{
    Outlook.Attachment myAttachment = (Outlook.Attachment)attachment;
    int sizeInBytes = myAttachment.Size;
    int sizeInKiloBytes = sizeInBytes / 1024;
    Marshal.ReleaseComObject(myAttachment);
 
    //Check if attachment is larger than 1MB
    if (sizeInKiloBytes >= 1024)
    {
        MessageBox.Show(
			"PLEASE NOTE: To keep mailbox sizes low, try and keep attachment under 1MB",
            "Attachment size warning");
    }
}

ProcessBeforeAttachmentAdd

This event was added in Outlook 2007 and is similar to ProcessAttachmentAdd except that it is raised before the attachment is added to the Outlook item. You also get an extra parameter enabling you to cancel the file attachment as illustrated below:

C# code example

public override void ProcessBeforeAttachmentAdd(object attachment,
    AddinExpress.MSO.ADXCancelEventArgs e)
{
    Outlook.Attachment myAttachment = (Outlook.Attachment)attachment;
    int sizeInBytes = myAttachment.Size;
    int sizeInKiloBytes = sizeInBytes / 1024;
    Marshal.ReleaseComObject(myAttachment);
 
    //Check if attachment is larger than 1MB
    if (sizeInKiloBytes >= 1024)
    {
        MessageBox.Show(
			"PLEASE NOTE: Attachment must be under 1MB. Attachment will be removed.",
            "Attachment size warning");
        e.Cancel = true;
    }
}

ProcessAttachmentRead

ProccessAttachmentRead will fire when the user opens an existing attachment on an Outlook item, which could include MailItem, TaskItem , ContactItem and AppointmentItem. As with the previous method a reference to the attachment is passed.

C# code example

public override void ProcessAttachmentRead(object attachment)
{
    Outlook._JournalItem journalItem = null;
 
    try
    {
        Outlook.Attachment myAttachment = (Outlook.Attachment)attachment;
        Outlook._Application outlookApp = ((AddinModule)this.Module).OutlookApp;
        string fileName = myAttachment.FileName;
 
        journalItem = (Outlook._JournalItem)outlookApp.CreateItem(
			Outlook.OlItemType.olJournalItem);
        journalItem.Subject = "You opened " + fileName + " today";
        journalItem.Save();
    }
    finally
    {
        if (journalItem != null)
            Marshal.ReleaseComObject(journalItem);
    }
}

ProcessAttachmentRemove

When the user deletes the attachment from the Outlook item the ProcessAttachmentRemove event will be raised, as with the previous methods you get a reference to the attachment.

C# code example

public override void ProcessAttachmentRemove(object attachment)
{
    Outlook.Attachment myAttachment = (Outlook.Attachment)attachment;
    Outlook._Application outlookApp = ((AddinModule)this.Module).OutlookApp;
 
    string fileName = String.Empty;
    Outlook._JournalItem journalItem = null;
 
    try
    {
        fileName = myAttachment.FileName;
 
    }
    catch (Exception)
    {
    }
 
    if (!String.IsNullOrEmpty(fileName))
    {
        try
        {
            journalItem = (Outlook._JournalItem)outlookApp.CreateItem(
				Outlook.OlItemType.olJournalItem);
            journalItem.Subject = "You removed " + fileName + " today";
            journalItem.Save();
        }
        finally
        {
            if (journalItem != null)
                Marshal.ReleaseComObject(journalItem);
        }
    }
}

ProcessBeforeAttachmentPreview

Introduced in Outlook 2007, you can use the ProcessBeforeAttachmentPreview method to add logic before an attachment is previewed in Outlook. A reference to the attachment is passed into the methods:

public override void ProcessBeforeAttachmentPreview(
	object attachment, AddinExpress.MSO.ADXCancelEventArgs e)
{
    Outlook.Attachment myAttachment = (Outlook.Attachment)attachment;
    Outlook._Application outlookApp = myAttachment.Application;
    string fullPath = @"C:\Temp\" + myAttachment.FileName;
    myAttachment.SaveAsFile(fullPath);
    Marshal.ReleaseComObject(myAttachment);
}

ProcessBeforeAttachmentRead

BeforeAttachmentRead was introduced in Outlook 2007 and will occur before the attached file of an Outlook object is read from the file system. A reference to the attachment is passed into the methods as well as ADXCancelEventArgs which can be used to cancel the operation.

C# code example

public override void ProcessBeforeAttachmentRead(
	object attachment, AddinExpress.MSO.ADXCancelEventArgs e)
{
    Outlook.Attachment myAttachment = (Outlook.Attachment)attachment;
    Outlook._Application outlookApp = myAttachment.Application;
    string fileName = myAttachment.FileName;
    Marshal.ReleaseComObject(myAttachment);
 
    if (fileName.ToLower().Contains("virus"))
    {
        MessageBox.Show(
			"WARNING: The file appears dangerous. Better not open it.",
            "Warning - Dangerous file");
        e.Cancel = true;
    }
}

ProcessBeforeAttachmentWriteToTempFile

When you double-click an attachment in Outlook in order to open it, the file will first be written to a temporary file location before opening. Use this method to intercept that event. You can use the ADXCancelEventArgs parameter to cancel the operation.

public override void ProcessBeforeAttachmentWriteToTempFile(
	object attachment, AddinExpress.MSO.ADXCancelEventArgs e)
{
    Outlook.Attachment myAttachment = (Outlook.Attachment)attachment;
    Outlook._Application outlookApp = myAttachment.Application;
    string fileName = myAttachment.FileName;
    Marshal.ReleaseComObject(myAttachment);
 
    if (fileName.ToLower().Contains("virus"))
    {
        MessageBox.Show(
			"WARNING: The file appears dangerous. Better not open it.",
            "Warning - Dangerous file");
        e.Cancel = true;
    }
}

ProcessBeforeAttachmentSave

The ProcessBeforeAttachmentSave is an interesting event. It is triggered when the attachment is saved to the messaging store and not when the user saves the attachment to disk. For example, if you have an MS Excel file attached to an Outlook contact item and the user double clicks on it, makes changes to the file and saves it, this event will only be triggered once the user saves the associated contact item.

public override void ProcessBeforeAttachmentSave(
	object attachment, AddinExpress.MSO.ADXCancelEventArgs e)
{
    Outlook.Attachment myAttachment = (Outlook.Attachment)attachment;
    Outlook._Application outlookApp = myAttachment.Application;
    string fileName = myAttachment.FileName;
 
    if (MessageBox.Show(
		"You've made changes to the attached file. " +
		"Would you like to save it to the central file system?",
        "File Changed", MessageBoxButtons.YesNo) == DialogResult.Yes)
    {
        myAttachment.SaveAsFile(@"K:\CentralStorage\" + fileName);
    }
 
    Marshal.ReleaseComObject(myAttachment);
}

ProcessBeforeCheckNames

The ProcessBeforeCheckNames method is used to intercept the BeforeCheckNames event, which occurs before Outlook starts to resolve the names of recipients of an Outlook item, for example when the user clicks on the Check Names button.

You can use this event to write your own contact name resolution logic.

public override void ProcessBeforeCheckNames(AddinExpress.MSO.ADXCancelEventArgs e)
{
    if (this.ItemObj is Outlook._MailItem)
    {
        Outlook.Recipient recipient = null;
        Outlook.Recipients recipients = null;
 
        Outlook._MailItem mail = (Outlook._MailItem)ItemObj;
 
        try
        {
            recipients = mail.Recipients;
            for (int i = 1; i <= recipients.Count; i++)
            {
                recipient = null;
 
                try
                {
                    recipient = recipients[i];
                }
                finally
                {
                    if (recipient != null)
                        Marshal.ReleaseComObject(recipient);
                }
            }
        }
        finally
        {
            if (recipients != null)
                Marshal.ReleaseComObject(recipients);
        }
    }
}

ProcessPropertyChange

Use the ProcessPropertyChange method to intercept when a built-in property on an Outlook item has changed. The name of the property that changed is passed into the method as a parameter.

public override void ProcessPropertyChange(string name)
{
    if (this.ItemObj is Outlook._MailItem)
    {
        Outlook._MailItem mail = (Outlook._MailItem)this.ItemObj;
 
        Outlook.ItemProperty property = null;
        Outlook.ItemProperties properties = null;
 
        try
        {
            properties = mail.ItemProperties;
            property = properties[name];
 
            MessageBox.Show(String.Format("You've changed {0} to {1}",
                name, property.Value));
        }
        finally
        {
            if (properties != null)
                Marshal.ReleaseComObject(properties);
            if (property != null)
                Marshal.ReleaseComObject(property);
        }
    }
}

ProcessCustomPropertyChange

When the user changes the value of a user property on an Outlook item, you can use the ProcessCustomPropertyChange event to intercept that event. The name of the user property is passed as a parameter.

public override void ProcessCustomPropertyChange(string name)
{
    if (this.ItemObj is Outlook._MailItem)
    {
        Outlook._MailItem mail = (Outlook._MailItem)this.ItemObj;
 
        Outlook.UserProperty userProperty = null;
        Outlook.UserProperties properties = null;
 
        try
        {
            properties = mail.UserProperties;
            userProperty = properties.Find(name);
            if (userProperty != null)
            {
                MessageBox.Show(String.Format(
					"You've changed the user property {0} to {1}",
					name, userProperty.Value));
            }
        }
        finally
        {
            if (userProperty != null)
                Marshal.ReleaseComObject(userProperty);
            if (properties != null)
                Marshal.ReleaseComObject(properties);
        }
    }
}

ProcessReply

When the user replies on an Outlook Item, the Reply event is raised. Use the ProcessReply method to intercept it. The response parameter is a reference to the new item that is being sent in response. In our example this will be an Outlook MailItem.

public override void ProcessReply(object response,
    AddinExpress.MSO.ADXCancelEventArgs e)
{
    if (response is Outlook._MailItem)
    {
        Outlook._MailItem mailResponse = (Outlook._MailItem)response;
        mailResponse.BCC = "someone@somewhere.com";
    }
}

ProcessReplyAll

The ProcessReplyAll is similar to the ProcessReply method. This event is raised when the user replies to all, on an Outlook item. The response parameter is a reference to the new item that is being sent in response and in our example this will be an Outlook MailItem.

public override void ProcessReplyAll(object response,
    AddinExpress.MSO.ADXCancelEventArgs e)
{
    if (response is Outlook._MailItem)
    {
        Outlook._MailItem mailResponse = (Outlook._MailItem)response;
        mailResponse.BCC = "everyone@everywhere.com";
    }
}

ProcessForward

The Forward event occurs when the user forwards an Outlook Item. Similar to the Reply event, a reference to the new item being forwarded is passed as a parameter as well as a Boolean with which you can cancel the event.

public override void ProcessForward(object forward,
    AddinExpress.MSO.ADXCancelEventArgs e)
{
    if (forward is Outlook._MailItem)
    {
        Outlook._MailItem mailForward = (Outlook._MailItem)forward;
        if (!mailForward.Subject.ToLower().Contains("confidential"))
        {
            mailForward.BCC = "mydropbox@work.com";
        }
        else
        {
            e.Cancel = true;
        }
    }
}

ProcessOpen

The Process event is raised when the user opens an Outlook item in an Inspector. Set the ADXCancelEventArgs’s Cancel property to true in order to cancel the open event.

public override void ProcessOpen(AddinExpress.MSO.ADXCancelEventArgs e)
{
    if (this.ItemObj is Outlook._MailItem)
    {
        Outlook._MailItem mailOpen = (Outlook._MailItem)ItemObj;
        Outlook._Application outlookApp = ((AddinModule)this.Module).OutlookApp;
 
        Outlook._JournalItem journalItem = null;
 
        try
        {
            journalItem = (Outlook._JournalItem)outlookApp.CreateItem(
				Outlook.OlItemType.olJournalItem);
            journalItem.Subject = 
				"You've read a mail with Subject: " + mailOpen.Subject + " today";
            journalItem.Save();
        }
        finally
        {
            if (journalItem != null)
                Marshal.ReleaseComObject(journalItem);
        }
    }
}

ProcessClose

ProcessClose is exactly the opposite of ProcessOpen and is raise when the user closes the Inspector of an Outlook item. As with ProcessOpen you can use the ADXCancelEventArgs to cancel the close operation.

public override void ProcessClose(AddinExpress.MSO.ADXCancelEventArgs e)
{
    if (this.ItemObj is Outlook._MailItem)
    {
        Outlook._MailItem mail = (Outlook._MailItem)ItemObj;
        if (mail.SenderEmailAddress != null &&
            mail.SenderEmailAddress.Equals("TheBoss@work.com"))
        {
            e.Cancel = true;
        }
    }
}

ProcessRead

The Read event is similar to the Open event except for the fact that it is also raised when the user selects the item in a view that supports in-cell editing.

public override void ProcessRead()
{
    if (this.ItemObj is Outlook._MailItem)
    {
        Outlook._MailItem mail = (Outlook._MailItem)ItemObj;
        Outlook._Application outlookApp = ((AddinModule)this.Module).OutlookApp;
 
        Outlook._JournalItem journalItem = null;
 
        try
        {
            journalItem = (Outlook._JournalItem)outlookApp.CreateItem(
				Outlook.OlItemType.olJournalItem);
            journalItem.Subject = 
				"You've read a mail with Subject: " + mail.Subject + " today";
            journalItem.Save();
        }
        finally
        {
            if (journalItem != null)
                Marshal.ReleaseComObject(journalItem);
        }
    }
}

ProcessWrite

The Write event is raised when a user saves an Outlook item or when the Save or SaveAs methods of the item is called. The Write event can also be cancelled.

public override void ProcessWrite(AddinExpress.MSO.ADXCancelEventArgs e)
{
    if (this.ItemObj is Outlook._MailItem)
    {
        Outlook._MailItem mail = (Outlook._MailItem)ItemObj;
        Outlook._Application outlookApp = ((AddinModule)this.Module).OutlookApp;
 
        Outlook._JournalItem journalItem = null;
 
        try
        {
            journalItem = (Outlook._JournalItem)outlookApp.CreateItem(
				Outlook.OlItemType.olJournalItem);
            journalItem.Subject = "Mail Saved: " + mail.Subject;
            journalItem.Save();
        }
        finally
        {
            if (journalItem != null)
                Marshal.ReleaseComObject(journalItem);
        }
    }
}

ProcessSend

When the user clicks send or you invoke the Send method on an Outlook Item, this event will fire. It can also be cancelled as with the previous methods.

public override void ProcessSend(AddinExpress.MSO.ADXCancelEventArgs e)
{
    if (this.ItemObj is Outlook._MailItem)
    {
        Outlook._MailItem mail = (Outlook._MailItem)ItemObj;
        Outlook._Application outlookApp = ((AddinModule)this.Module).OutlookApp;
 
        Outlook._JournalItem journalItem = null;
 
        try
        {
            journalItem = (Outlook._JournalItem)outlookApp.CreateItem(
				Outlook.OlItemType.olJournalItem);
            journalItem.Subject = "Sent an e-mail to " + mail.To;
            journalItem.Save();
        }
        finally
        {
            if (journalItem != null)
                Marshal.ReleaseComObject(journalItem);
        }
    }
}

ProcessBeforeDelete

When you invoke the Delete method or the user deletes an Outlook Item, the BeforeDelete events will be raised. A reference to the item being deleted is passed as a parameter.

public override void ProcessBeforeDelete(
	object item, AddinExpress.MSO.ADXCancelEventArgs e)
{
    if (item is Outlook._MailItem)
    {
        Outlook._MailItem mail = (Outlook._MailItem)item;
        if (mail.To.Contains("TheBoss@work.com"))
        {
            Outlook._Application outlookApp = ((AddinModule)this.Module).OutlookApp;
 
            Outlook._JournalItem journalItem = null;
 
            try
            {
                journalItem = (Outlook._JournalItem)outlookApp.CreateItem(
					Outlook.OlItemType.olJournalItem);
                journalItem.Subject = "Oh oh! You deleted an email from the boss";
                journalItem.Save();
            }
            finally
            {
                if (journalItem != null)
                    Marshal.ReleaseComObject(journalItem);
            }
        }
    }
}

ProcessUnload

The ProcessUnload event is raised after the Close event and before the Outlook item is unloaded from memory. You can use this event to release any resources related to the object.

ProcessBeforeAutoSave

If the user has Auto save enabled in Outlook, this event will fire just before Outlook automatically saves the item. You can cancel this by setting ADXCancelEventArgs.Cancel to true.

public override void ProcessBeforeAutoSave(AddinExpress.MSO.ADXCancelEventArgs e)
{
    if (this.ItemObj is Outlook._MailItem)
    {
        Outlook._MailItem mail = (Outlook._MailItem)ItemObj;
 
        Outlook.UserProperties properties = null;
        Outlook.UserProperty newUserProperty = null;
 
        try
        {
            properties = mail.UserProperties;
            newUserProperty = properties.Add("AutoSaved", 
				Outlook.OlUserPropertyType.olDateTime);
            newUserProperty.Value = DateTime.Now;
        }
        finally
        {
            if (newUserProperty != null)
                Marshal.ReleaseComObject(newUserProperty);
            if (properties != null)
                Marshal.ReleaseComObject(properties);
        }
    }
}

ProcessBeforeRead

The ProcessBeforeRead event is raised before an item’s properties are read by Outlook; it occurs after the Read event and cannot be cancelled. An interesting caveat is that you can only access the Class and MessageClass properties of the item. If you try and access any other property you will receive an exception.

ProcessAfterWrite

The ProcessAtterWrite occurs after the Outlook item has been saved and after the Write event. As with the BeforeRead event it cannot be cancelled. Please note you can only access the Class and MessageClass properties of the item.

For more information about Outlook 2007 events, please see the Microsoft documentation. If you’re looking for more information on the Outlook 2010 events you can find it here.

Thank you for reading. Until next time, keep coding!

Available downloads:

This sample add-in was developed using Add-in Express for Office and .net:
C# sample add-in

You may also be interested in:

• Outlook Items and Folders events explained