Implementing a Form Region to Display Email Headers in Outlook 2010

Summary:  Learn how to customize the mail inspector in Microsoft Outlook 2010 so that with the click of a button, Outlook can display the Internet headers of the current message.

Applies to: Office 2010 | Outlook 2010 | Visual Studio

Published:  February 2011

Provided by:  Angela Chu-Hatoun, Microsoft Corporation

Internet headers provide detailed information about an email message. Such information includes the servers that processed the message before it was finally delivered to the recipient. By default, some information is exposed in the email client, and other information is hidden. For example, Microsoft Outlook 2010 displays the date and time that a message is received. However, the Internet headers reveal the actual date and time that the sender sent the message. This Visual How To shows how to programmatically obtain header information about an email message. To conveniently display such information, the Visual How To uses an adjoining form region. When you open an email message in Outlook, you will see the form region at the bottom of the mail inspector, and can click a button to view the Internet headers of that message. The sample provided with this Visual How To uses a C# Outlook 2010 add-in that customizes the standard email message form with an adjoining form region. To use this sample, you should already be familiar with C# and creating add-ins for Outlook. Code Sample Files The Outlook add-in solution is named OutlookDisplayHeaders_CS. It contains an adjoining form region that has the name Display Internet Headers and is represented by the form region class FormRegion1. FormRegion1 provides a button and a text box. The button is labeled Show Headers. When you click the Show Headers button, the Internet headers of the currently displayed email message are shown in the text box. Creating the Form Region For simplicity, this Visual How To creates the add-in by using the Outlook 2010 Add-in template, and creates an adjoining form region by using the Outlook Form Region template in Microsoft Visual Studio 2010. For more information about how to create the add-in and form region, see the accompanying video. Implementing the Button Click Event Outlook displays the adjoining form region, Display Internet Headers, when it opens an email message in an inspector. When a click event for the Show Headers button occurs, the add-in uses this.OutlookItem to get a reference to the current Outlook mail item. This technique uses the Visual Studio Tools for Office API. For more information, see the OutlookItem() property. After getting a reference to the current mail item, the add-in uses the item’s PropertyAccessor interface to access the MAPI PidTagTransportMessageHeaders property. This property represents the Internet headers for that mail item. The add-in displays the Internet headers in the text box. Every email message that you receive over the Internet contains a set of Internet headers. Internet headers provide details about the message, such as who created the message, the email client used to compose it, and the email servers it passed through on its way to the recipient. These details can identify problems with the message or help discover the sources of unsolicited commercial messages. To see an example of the Internet headers for an email message, follow these steps. To see the Internet headers for an email message Open the message in Outlook 2010. Click File, and then click Properties. Look for the section Internet headers at the bottom of the Properties dialog box. Outlook uses some header information, such as the information in the From, To, and Sent fields in an Outlook message. For more information about common Internet headers, see View e-mail message headers. Note The information in Internet headers can be modified for malicious reasons. The practice of providing false information in message headers is known as spoofing and is a growing problem. For example, a message might indicate that it is from Eric Lang at Alpine Ski House (ericlang@alpineskihouse.com) when it is actually from a malicious bulk email service. Accessing the MAPI PidTagTransportMessageHeaders Property Outlook provides a PropertyAccessor interface that you can use to get and set built-in properties that are not exposed in the Outlook object model. Among these properties are those in the Messaging Application Programming Interface (MAPI) namespaces. The PidTagTransportMessageHeaders property is an example of these properties in the MAPI proptag namespace. The PidTagTransportMessageHeaders property specifies the transport-specific message header information for an email message. You can use the PropertyAccessor object to reference this property in the following format: https://schemas.microsoft.com/mapi/proptag/0x007D001E https://schemas.microsoft.com/mapi/proptag specifies the proptag namespace, 007d specifies the MAPI property identifier for this property, and 001E specifies a single-value or multiple-value property type of a null-terminated 8-bit (2-byte) character string. For ease of reading, use a constant to define the schema representation of the PidTagTransportMessageHeaders property as follows: string PidTagTransportMessageHeaders = @"https://schemas.microsoft.com/mapi/proptag/0x007D001E"; To obtain the message header information for an email message, use the PropertyAccessor object exposed on the email message (by using the PropertyAccessor property), and use the GetProperty(String) method to access the property as follows: message.PropertyAccessor.GetProperty (PidTagTransportMessageHeaders) Note You should not assume that all email messages that are delivered to your mailbox contain Internet headers. Use a try...catch statement to avoid an exception if you open an email that does not specify the PidTagTransportMessageHeaders property. Outlook Items, Forms, and Adjoining Form Regions Outlook supports different types of items such as appointments, contacts, mail messages, and tasks. Every Outlook item has a message class property. The following list shows examples of different types of items and their default message class: Appointment: IPM.Appointment Contact: IPM.Contact Mail message: IPM.Note Task: IPM.Task Outlook uses specific forms to display different types of items. This is achieved by the message class—each form is also associated with a message class, which Outlook uses to identify the form to use to display the item. Outlook supports customizing a standard form by creating a form page or a form region. Each form contains one or more form pages, and the default page is the first form page that you see when Outlook opens the item. An adjoining form region is a form region added to the bottom of the default page of a standard Outlook form. You can add a new user interface as an adjoining form region to the default page of any standard Outlook form. This Visual How To uses an adjoining form region as a convenient way to display Internet headers when you open a mail message in Outlook. The adjoining form region contains a custom user interface—a button and a text box—that displays the Internet headers for that mail message in the text box when you click the button. Programmatically, you create an add-in that supports the adjoining form region for items of the IPM.Note message class, traps the button click event, uses the PropertyAccessor of the opened mail item to get its value of the PidTagTransportMessageHeaders property, and displays that value in the text box as Internet headers. Note Once you add a form region to the inspector for a message class, the form region always exists in the inspector for that message class. If you prefer not to have the form region expanded upon opening every item of that message class, you can collapse the form region before closing it, and Outlook will remember that preferred setting subsequently. For more information about the techniques discussed in this article, see the Explore It section.

Watch the video > [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/46c2c809-fe59-488c-a56c-50389b01f4fd] Length: 7:51 Grab the Code Outlook Developer Center View the Internet header information for an email message View e-mail message headers Referencing Properties by Namespace Best Practices for Getting and Setting Properties MAPI Property Tags MAPI Property Identifier Overview MAPI Property Type Overview Property Identifier Ranges Property Types Form Regions How to: Add a Form Region to an Outlook Add-in Project