Setting an Outlook Contacts Form Field By Using the EWS Managed API
By Steve Petersen
The Microsoft Exchange Web Services (EWS) Managed API includes a method that enables you to easily manipulate extended properties. And because you can use extended properties to customize Microsoft Office Outlook, you can manipulate extended properties to set the fields of objects that are derived from the Item class.
In this article, I describe how to customize Contact object fields in Outlook by using the EWS Managed API. I also provide a complete list of the PropertyId values that you can use to customize Contact object fields, in the section Contact Item PropertyID Values later in this article.
For more information about Contact object properties, see ContactItemClass.
The following examples show how to use the EWS Managed API to create a contact, set the property, add extended properties to the contact, and save the contact to the Exchange server. Contacts and their extended properties are available on the Outlook form.
To perform this task, you must be connected to an Exchange server that hosts EWS. For information about how to connect to an Exchange server, see Connecting to EWS by using the EWS Managed API in the Explore the EWS Managed API.
Creating a Contact
The following example shows how to use the EWS Managed API to create a contact. In this example, five first-class properties are added to the contact.
 Note |
|---|
This example assumes that service is a valid ExchangeService binding. |
For more information about how to create contacts, see Creating contacts by using the EWS Managed API in the Explore the EWS Managed API.
Setting the Property Set for the Outlook Form
When you create a contact, you must specify a property set identifier for the properties that are associated with a contact item. For Outlook contacts, the GUID that defines the property set is {00062004-0000-0000-C000-000000000046}.
Adding Extended Properties
After you create a contact, you can customize the contact by creating extended properties and adding the extended properties to the Outlook form. For more information about how to create extended properties, see Creating custom extended properties by using the EWS Managed API in the Explore the EWS Managed API.
You can add multiple extended properties. In this example, only one extended property is defined for the contact. For a list of the extended properties that you can add to a contact, see Contact Item PropertyID Values.
Saving the Contact
After you create and add extended properties to a contact, save the contact to the Exchange mailbox. After the contact is saved to the server, it can be viewed in Outlook.
Code Example
The following example shows how to create a contact, create extended properties, set a value for three extended properties, and add them to the contact.
// Create a contact. Use first-class properties. Contact contact = new Contact(service); contact.GivenName = "Ann"; contact.MiddleName = "Middle"; contact.NickName = "Annie"; contact.Surname = "Beebe"; contact.DisplayName = contact.Surname; // The Outlook form. Guid propertySetId = new Guid("{00062004-0000-0000-C000-000000000046}"); // Use the extended properties for these non-first-class properties. // Set the Outlook contact form. // User Field 1 ExtendedPropertyDefinition extProp1 = new ExtendedPropertyDefinition( propertySetId, 0x804F, MapiPropertyType.String); contact.SetExtendedProperty(extProp1, "User1 field"); // User Field 2 ExtendedPropertyDefinition extProp2 = new ExtendedPropertyDefinition( propertySetId, 0x8050, MapiPropertyType.String); contact.SetExtendedProperty(extProp2, "User2 field"); // Journal ExtendedPropertyDefinition extPropjournal = new ExtendedPropertyDefinition( propertySetId, 0x8025, MapiPropertyType.Boolean); contact.SetExtendedProperty(extPropjournal, "true"); contact.Save();
XML Request
The following example shows the XML request that is sent to the server to create a contact that has the extended properties that are used in this example.
For information about how to view the XML requests and responses, see Tracing EWS requests in the Explore the EWS Managed API.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2010_SP1" />
</soap:Header>
<soap:Body>
<m:CreateItem MessageDisposition="SaveOnly">
<m:Items>
<t:Contact>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertySetId="00062004-0000-0000-c000-000000000046"
PropertyId="32847" PropertyType="String" />
<t:Value>User1 field</t:Value>
</t:ExtendedProperty>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertySetId="00062004-0000-0000-c000-000000000046"
PropertyId="32848" PropertyType="String" />
<t:Value>User2 field</t:Value>
</t:ExtendedProperty>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertySetId="00062004-0000-0000-c000-000000000046"
PropertyId="32805" PropertyType="Boolean" />
<t:Value>true</t:Value>
</t:ExtendedProperty>
<t:DisplayName>Beebe</t:DisplayName>
<t:GivenName>Ann</t:GivenName>
<t:MiddleName>Middle</t:MiddleName>
<t:Nickname>Annie</t:Nickname>
<t:Surname>Beebe</t:Surname>
</t:Contact>
</m:Items>
</m:CreateItem>
</soap:Body>
</soap:Envelope>
XML Response
The following example shows the XML response that is returned when the contact, with the extended properties, is generated. The values of the Id and the ChangeKey attributes of the Contact element have been shortened for readability.
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:ServerVersionInfo MajorVersion="14"
MinorVersion="1"
MajorBuildNumber="206"
MinorBuildNumber="0"
Version="Exchange2010_SP1"
xmlns:h="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
</s:Header>
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<m:CreateItemResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:CreateItemResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:Items>
<t:Contact>
<t:ItemId Id="AAMkADI5Zjc0N" ChangeKey="EQAAABYAAAA" />
</t:Contact>
</m:Items>
</m:CreateItemResponseMessage>
</m:ResponseMessages>
</m:CreateItemResponse>
</s:Body>
</s:Envelope>
Contact Item PropertyID Values
The following table lists the Contact object extended properties and the PropertyId values that can be used to set the fields of the Contact object. These PropertyId values are used with the PropertySetId of {00062004-0000-0000-C000-000000000046} to set the extended properties of the Contact object.
For more information about contact item properties, see ContactItemClass.
Contact object extended property | PropertyId (Decimal Hexadecimal) | First Class Property |
|---|---|---|
Account | 14848 (0x3A00) | Not applicable |
Actions | 63511 (0xF817) | Not applicable |
Anniversary | 14913 (0x3A41) | |
Application | 61440 (0xF000) | Not applicable |
AssistantName | 14896 (0x3A30) | |
AssistantTelephoneNumber | 14894 (0x3A2E) | |
Attachments | 63509 (0xF815) | Not applicable |
AutoResolvedWinner | 64186 (0xFABA) | Not applicable |
BillingInformation | 34101 (0x8535) | Not applicable |
Birthday | 14914 (0x3A42) | |
Body | 37120 (0x9100) | |
Business2TelephoneNumber | 14875 (0x3A1B) | |
BusinessAddress | 32795 (0x801B) | Not applicable |
BusinessAddressCity | 32838 (0x8046) | Not applicable |
BusinessAddressCountry | 32841 (0x8049) | Not applicable |
BusinessAddressPostalCode | 32840 (0x8048) | Not applicable |
BusinessAddressPostOfficeBox | 32842 (0x804A) | Not applicable |
BusinessAddressState | 32839 (0x8047) | Not applicable |
BusinessAddressStreet | 32837 (0x8045) | Not applicable |
BusinessCardLayoutXml | 64525 (0xFC0D) | Not applicable |
BusinessCardType | 64528 (0xFC10) | Not applicable |
BusinessFaxNumber | 14884 (0x3A24) | |
BusinessHomePage | 14929 (0x3A51) | |
BusinessTelephoneNumber | 14856 (0x3A08) | |
CallbackTelephoneNumber | 14850 (0x3A02) | |
CarTelephoneNumber | 14878 (0x3A1E) | |
Categories | 36865 (0x9001) | |
Children | 32780 (0x800C) | |
Class | 61450 (0xF00A) | Not applicable |
Companies | 34107 (0x853B) | |
CompanyAndFullName | 32792 (0x8018) | Not applicable |
CompanyLastFirstNoSpace | 32818 (0x8032) | Not applicable |
CompanyLastFirstSpaceOnly | 14921 (0x3A49) | Not applicable |
CompanyMainTelephoneNumber | 14935 (0x3A57) | Not applicable |
CompanyName | 14870 (0x3A16) | |
ComputerNetworkName | 14921 (0x3A49) | Not applicable |
Conflicts | 64187 (0xFABB) | Not applicable |
ConversationID | 64629 (0xFC75) | |
ConversationIndex | 64192 (0xFAC0) | Not applicable |
ConversationTopic | 112 (0x70) | Not applicable |
CreationTime | 12295 (0x3007) | Not applicable |
CustomerID | 14922 (0x3A4A) | Not applicable |
Department | 14872 (0x3A18) | |
DownloadState | 64077 (0xFA4D) | Not applicable |
Email1Address | 32899 (0x8083) | |
Email1AddressType | 32898 (0x8082) | Not applicable |
Email1DisplayName | 32896 (0x8080) | |
Email1EntryID | 32901 (0x8085) | |
Email2Address | 32915 (0x8093) | |
Email2AddressType | 32914 (0x8092) | Not applicable |
Email2DisplayName | 32912 (0x8090) | |
Email2EntryID | 32917 (0x8095) | |
Email3Address | 32931 (0x80A3) | |
Email3AddressType | 32930 (0x80A2) | Not applicable |
Email3DisplayName | 32928 (0x80A0) | |
Email3EntryID | 32933 (0x80A5) | |
EntryID | 61470 (0xF01E) | |
FileAs | 32773 (0x8005) | |
FirstName | 14854 (0x3A06) | Not applicable |
FormDescription | 61589 (0xF095) | Not applicable |
FTPSite | 14924 (0x3A4C) | Not applicable |
FullName | 12289 (0x3001) | Not applicable |
FullNameAndCompany | 32793 (0x8019) | Not applicable |
Gender | 14925 (0x3A4D) | Not applicable |
GovernmentIDNumber | 14855 (0x3A07) | Not applicable |
HasPicture | 64191 (0xFABF) | |
Hobby | 14915 (0x3A43) | Not applicable |
Home2TelephoneNumber | 14895 (0x3A2F) | |
HomeAddress | 32794 (0x801A) | Not applicable |
HomeAddressCity | 14937 (0x3A59) | Not applicable |
HomeAddressCountry | 14938 (0x3A5A) | Not applicable |
HomeAddressPostalCode | 14939 (0x3A5B) | Not applicable |
HomeAddressPostOfficeBox | 14942 (0x3A5E) | Not applicable |
HomeAddressState | 14940 (0x3A5C) | Not applicable |
HomeAddressStreet | 14941 (0x3A5D) | Not applicable |
HomeFaxNumber | 14885 (0x3A25) | |
HomeTelephoneNumber | 14895 (0x3A2F) | |
IMAddress | 32866 (0x8062) | Not applicable |
Importance | 23 (0x17) | |
Initials | 14858 (0x3A0A) | |
InternetFreeBusyAddress | 32984 (0x80D8) | Not applicable |
IsConflict | 64164 (0xFAA4) | Not applicable |
ISDNNumber | 14893 (0x3A2D) | Not applicable |
IsMarkedAsTask | 64522 (0xFC0A) | Not applicable |
ItemProperties | 64009 (0xFA09) | Not applicable |
JobTitle | 14871 (0x3A17) | |
Journal | 32805 (0x8025) | Not applicable |
Language | 14860 (0x3A0C) | Not applicable |
LastFirstAndSuffix | 32822 (0x8036) | Not applicable |
LastFirstNoSpace | 32816 (0x8030) | Not applicable |
LastFirstNoSpaceAndSuffix | 32824 (0x8038) | Not applicable |
LastFirstNoSpaceCompany | 32820 (0x8034) | Not applicable |
LastFirstSpaceOnly | 32817 (0x8031) | Not applicable |
LastFirstSpaceOnlyCompany | 32821 (0x8035) | Not applicable |
LastModificationTime | 12296 (0x3008) | |
LastName | 14865 (0x3A11) | |
LastNameAndFirstName | 32791 (0x8017) | Not applicable |
Links | 62469 (0xF405) | Not applicable |
MailingAddress | 14869 (0x3A15) | Not applicable |
MailingAddressCity | 14887 (0x3A27) | Not applicable |
MailingAddressCountry | 14886 (0x3A26) | Not applicable |
MailingAddressPostalCode | 14890 (0x3A2A) | Not applicable |
MailingAddressPostOfficeBox | 14891 (0x3A2B) | Not applicable |
MailingAddressState | 14888 (0x3A28) | Not applicable |
MailingAddressStreet | 14889 (0x3A29) | Not applicable |
ManagerName | 14926 (0x3A4E) | |
MAPIOBJECT | 61696 (0xF100) | Not applicable |
MarkForDownload | 34161 (0x8571) | Not applicable |
MessageClass | 26 (0x1A) | Not applicable |
MiddleName | 14916 (0x3A44) | |
Mileage | 34100 (0x8534) | |
MobileTelephoneNumber | 14876 (0x3A1C) | |
NetMeetingAlias | 32863 (0x805F) | Not applicable |
NetMeetingServer | 32864 (0x8060) | Not applicable |
NickName | 14927 (0x3A4F) | |
NoAging | 34062 (0x850E) | Not applicable |
OfficeLocation | 14873 (0x3A19) | |
OrganizationalIDNumber | 14864 (0x3A10) | Not applicable |
OtherAddress | 32796 (0x801C) | Not applicable |
OtherAddressCity | 14943 (0x3A5F) | Not applicable |
OtherAddressCountry | 14944 (0x3A60) | Not applicable |
OtherAddressPostalCode | 14945 (0x3A61) | Not applicable |
OtherAddressPostOfficeBox | 14948 (0x3A64) | Not applicable |
OtherAddressState | 14946 (0x3A62) | Not applicable |
OtherAddressStreet | 14947 (0x3A63) | Not applicable |
OtherFaxNumber | 14883 (0x3A23) | |
OtherTelephoneNumber | 14879 (0x3A1F) | |
OutlookInternalVersion | 34130 (0x8552) | Not applicable |
OutlookVersion | 34132 (0x8554) | Not applicable |
PagerNumber | 14881 (0x3A21) | |
Parent | 61441 (0xF001) | Not applicable |
PersonalHomePage | 14928 (0x3A50) | Not applicable |
PrimaryTelephoneNumber | 14874 (0x3A1A) | |
Profession | 14918 (0x3A46) | |
PropertyAccessor | 64253 (0xFAFD) | Not applicable |
RadioTelephoneNumber | 14877 (0x3A1D) | |
ReferredBy | 14919 (0x3A47) | Not applicable |
ReminderOverrideDefault | 34076 (0x851C) | Not applicable |
ReminderPlaySound | 34078 (0x851E) | Not applicable |
ReminderSet | 34051 (0x8503) | Not applicable |
ReminderSoundFile | 34079 (0x851F) | Not applicable |
ReminderTime | 34050 (0x8502) | Not applicable |
RTFBody | 64644 (0xFC84) | Not applicable |
Saved | 61603 (0xF0A3) | Not applicable |
SelectedMailingAddress | 32802 (0x8022) | Not applicable |
Sensitivity | 54 (0x36) | |
Session | 61451 (0xF00B) | Not applicable |
Size | 3592 (0xE08) | |
Spouse | 14920 (0x3A48) | |
Subject | 55 (0x37) | |
Suffix | 14853 (0x3A05) | Not applicable |
TaskCompletedDate | 33039 (0x810F) | Not applicable |
TaskDueDate | 33029 (0x8105) | Not applicable |
TaskStartDate | 33028 (0x8104) | Not applicable |
TaskSubject | 64543 (0xFC1F) | Not applicable |
TelexNumber | 14892 (0x3A2C) | |
Title | 14917 (0x3A45) | Not applicable |
ToDoTaskOrdinal | 34208 (0x85A0) | Not applicable |
TTYTDDTelephoneNumber | 14923 (0x3A4B) | Not applicable |
UnRead | 61468 (0xF01C) | Not applicable |
User1 | 32847 (0x804F) | Not applicable |
User2 | 32848 (0x8050) | Not applicable |
User3 | 32849 (0x8051) | Not applicable |
User4 | 32850 (0x8052) | Not applicable |
UserCertificate | 32790 (0x8016) | Not applicable |
UserProperties | 63510 (0xF816) | Not applicable |
WebPage | 32811 (0x802B) | Not applicable |
YomiCompanyName | 32814 (0x802E) | Not applicable |
YomiFirstName | 32812 (0x802C) | Not applicable |
YomiLastName | 32813 (0x802D) | Not applicable |
