New Outlook Documentation Part 1 – Contact Linking

[This is now documented here:,,]

This information was also published as

Recently the Outlook development team has agreed to document some bits and pieces about Outlook that we’ve never documented before. I’ve been charged with getting this documentation out to the development community. After publishing the information here, my next step will be to take your feedback and submit this as an article in our Knowledge Base. This information may also show up in a future release of the MSDN.

The first I’ll be covering – The Contact Address Book

Relating Contact Address Book entries to Contact messages, reading e-mail addresses from Contact messages, and locating Contact photos on Contact messages

Outlook 2003 ships with a Contact Address Book provider, contab32.dll. This provider presents information from a user’s Contacts folder in the form of an address book so that the contacts may be used to address e-mail messages. All Contacts which have an e-mail address or fax number will be represented in the address book, with a separate listing for each e-mail address or fax number. Since a Contact may have 3 e-mail addresses and 3 fax numbers, this means each Contact may be represented by up to 6 separate entries in the address book.

The information present on a Contact Address Book entry is a subset of the information present on the underlying Contact message. The following structure can be used to determine which Contact message a particular Contact Address Book entry is derived from.


#pragma pack(4)
typedef struct _contab_entryid
BYTE misc1[4];
MAPIUID misc2;
ULONG misc3;
ULONG misc4;
ULONG misc5;
// EntryID of contact in store.
ULONG cbeid;
BYTE abeid[1];
#pragma pack()


The CONTAB_ENTRYID structure defines the format of the entry IDs of IMailUser objects used in the Outlook Address Book.

Entry IDs of this type could be obtained from the PR_ENTRYID column of the Outlook Address Book’s contents table or from the PR_ENTRYID property on an IMailUser object opened from the Outlook Address Book.

To open the underlying Contact message, cast the Contact Address Book entry ID to this structure and then use the cbeid and abeid members as the Contact’s entry ID. For example:

HRESULT HrOpenContact(
   ULONG cbEntryID,
   ULONG ulFlags,
   LPMESSAGE* lpContactMessage)
   ULONG ulObjType = NULL;

   if (sizeof(CONTAB_ENTRYID) > cbEntryID) return MAPI_E_INVALID_PARAMETER;

   HRESULT hRes = lpSession->OpenEntry(
      (LPENTRYID) lpContabEID->abeid,
      (LPUNKNOWN*) lpContactMessage);

   return hRes;

Contact E-Mail Addresses

The only way to access the e-mail addresses on a Contact message is through named properties on the message. These properties documented here are only supported as read-only properties. We cannot support solutions which write to these properties.


DEFINE_OLEGUID(PSETID_Address,		MAKELONG(0x2000+(0x04),0x0006),0,0);
#define dispidEmailAddrType		0x8082
#define dispidEmailEmailAddress		0x8083
#define dispidEmail2AddrType		0x8092
#define dispidEmail2EmailAddress	0x8093
#define dispidEmail3AddrType		0x80A2
#define dispidEmail3EmailAddress	0x80A3



Use these to fill out the MAPINAMEID structure. PSETID_Adress is the lpGuid, MNID_ID is the ulKind, and the various dispids are the lID’s. Then use GetIDsFromNames to get the current property IDs for these props. All of these properties are string properties. For example:

HRESULT HrGetEmail1(LPMESSAGE lpContact)
   HRESULT         hRes = S_OK;
   LPSPropTagArray lpNamedPropTags = NULL;
   MAPINAMEID      NamedID = {0};
   LPMAPINAMEID    lpNamedID = &NamedID;
   NamedID.lpguid = (LPGUID)&PSETID_Address;
   NamedID.ulKind = MNID_ID;
   NamedID.Kind.lID = dispidEmailEmailAddress;

   hRes = lpContact->GetIDsFromNames(

   if (SUCCEEDED(hRes) && lpNamedPropTags)
      SPropTagArray sPropTagArray;
      sPropTagArray.cValues = 1;
      sPropTagArray.aulPropTag[0] = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[0],PT_STRING8);
      LPSPropValue lpProps = NULL;
      ULONG cProps = 0;

      hRes = lpContact->GetProps(
      if (SUCCEEDED(hRes) && 
         1 == cProps && 
         lpProps && 
         PT_STRING8 == PROP_TYPE(lpProps[0].ulPropTag) &&
         printf("Email address 1 = \"%s\"\n",lpProps[0].Value.lpszA);
   return hRes;

Contact Pictures

Outlook supports a single picture for each contact. This picture is stored as an attachment on the contact’s underlying message. To determine which attachment is the picture, use the PR_ATTACHMENT_CONTACTPHOTO property. The property documented here is only supported as a read-only property. We cannot support solutions which write to this property.




The PR_ATTACHMENT_CONTACTPHOTO property can be accessed as a column on the attachment table obtained through IMessage::GetAttachmentTable, or as a property on the IAttach object. If this value is true, then the attachment is the contact picture. The picture will be store as a JPEG formatted file. Use the normal MAPI methods to extract this attachment to a file.

[Update: 1/23/06 – added KB link]

Comments (13)

  1. Sergei M. Zinovyev says:

    I think there is also a way to construct EntryID of ContactsAddressBook (IABContainer) for given Contacts folder (IFolder) in message store.

    The same question about EntryID of IDistList?

    Could you please comment these?

    Sergei M. Zinovyev

  2. Sergei,

    We’re not planning right now on documenting either of those.


  3. Sergei M. Zinovyev says:


    I tried to compare 2 EntryIDs.

    EntryID1: EntryID of IContactItem:

    Length: 70 (0x00000046)

    Bytes: 0000000001721DE10010974CB63B86B288492A640700DCA67530B8BEA74586EA9FFE572E294D00000041B1950000DCA67530B8BEA74586EA9FFE572E294D000000FA6A430000

    EntryID2: EntryID of IMailUser:

    Length: 109 (0x0000006d)



    Let me analyze the second:

    BYTE misc1[4];


    MAPIUID misc2; // 16 bytes


    ULONG misc3; // Always 3?


    ULONG misc4; // Always 4?


    ULONG misc5; // Index of address info in ContactItem: 0, 1, or 2.


    // EntryID of contact in store, equils to EntryID1



    // The last 3 bytes. (???)


    What are the last 3 bytes in EntryID of IMailUser? I cannot open IMailUser if I use EntryID without these 3 bytes.

    Sergei M. Zinovyev

  4. Charles Newfield says:

    I want information on how to import the Earthlink address book into outlook contacts and there doesn’t seem to be any information on how to do this.

    It is a bit more complicated than just importing a csv file into Outlook Contacts from a csv formatted file that was exported from Earthlink. The fields do not match and even after I set up the fields to match the email addresses are not imported even though they exist in the csv file.

  5. Sergei,

    The entry ID is, as noted in the cbeid field, 70 bytes. So that there may be additional information after the entry ID is not relevent. This documentation is not intended to instruct you in building Contab entry IDs – only in mapping such entry IDs back to their source contact messages.


    Your question is not related to the topic of this post. Perhaps you should try an Outlook related newsgroup.


  6. Sergei M. Zinovyev says:


    Yes, you have documented the way how to get EntryID of IMessage from EntryID of IMailUser.

    You sad "A" and I just wish to say "B". And I undestand that you did not document the way how to construct EntryID of IMailUser for EMail1(2, 3) of ContactItem.


  7. huandao says:


    I got "error LNK2001: unresolved external symbol _PSETID_Address" and "fatal error LNK1120: 1 unresolved externals" when compile this code.

    I know it is linking problem but don’t know which library should be added.

    Thanks for your help.


  8. Nope – that’s not a linking problem. In one of your source files you need to #define INITGUID before including initguid.h and your DEFINE_OLEGUID statement.

    BTW, this is discussed in which does apply to DEFINE_OLEGUID.

  9. huandao says:

    Thanks Stephen, I got it compiled.

    I’m also looking for documentation about using MAPI forms (such as Contact Detail, Email messages ,and so on. Do you know where to get it?

    Many thanks,


  10. Just for completeness sale, the following named property must be set to true on the message when adding a contact picture:

    {00062004-0000-0000-C000-000000000046}, 0x8015, PT_BOOLEAN

  11. We had a customer report recently that when he tried to fetch certain properties using the Outlook Object

  12. Pete Thomas says:

    I’m using the builtin table linking to find duplicate phone numbers, thus:

    SELECT First, Last, Phone, 1 As Type

    FROM Contacts Where Phone is not null


    SELECT First, Last,  [Mobile Phone], 2

    FROM Contacts Where [Mobile Phone] is not null


    SELECT First, Last, [Pager Phone], 3

    FROM Contacts Where [Pager Phone] is not null


    SELECT First, Last,  [Home2 Phone], 4

    FROM Contacts Where [Home2 Phone] is not null


    SELECT First, Last, [Assistant Phone Number], 5

    FROM Contacts Where [Assistant Phone Number] is not null


    SELECT First, Last, [Business Fax], 6

    FROM Contacts where [Business Fax] is not null


    SELECT First, Last,  [Home Fax], 7

    FROM Contacts where [Home Fax] is not null


    SELECT First, Last, [Other Fax], 8

    FROM Contacts where [Other Fax] is not null

    UNION SELECT First, Last, [Telex Number], 9

    FROM Contacts where [Telex Number] is not null;

    The problem is that I need the object’s {U|GUID} to do the update query when I determine phone numbers that I want to change.  The UNION carry cannot carry the EntryID property through.

    Any ideas?

  13. I don’t know what you mean when you say "builtin table linking". Those look like SQL statements to me. Have you installed some component that allows you to access MAPI using SQL statements?