Programmatically updating Outlook's address book options with a command line tool

I recently found the need to configure Outlook 2003 for thousands of corporate users to use preferred address book settings instead of the defaults. As anyone in a large corporate environment may know, the defaults are set such that when composing an email, name resolution checks all address lists in Exchange in alphabetical order by list, then name. When an organization is many tens of thousands large, resolving "Smith" will inevitably find conflicts.

MAPI Schmappy
I recently found the need to configure Outlook 2003 for thousands of corporate users to use preferred address book settings instead of the defaults. As anyone in a large corporate environment may know, the defaults are set such that when composing an email, name resolution checks all address lists within the Global Address List alphabetically by list, then name. When an organization is many tens of thousands large, resolving "Smith" will inevitably find conflicts and irrelevant matches.

To ease the pain, it would be nice to resolve against the address list containing only names in your local organization before all others. This can be set manually in the Addressing dialog, found in Outlook address book's Tools->Options menu. Then, add the preferred address list to the top (see figure right).

You can also set the default address list, which defines which address list the Address Book will initially display and search upon. This should probably also be set to your local organization, instead of "All Contacts".

The Problem
There are no command line or scripting tools that do this for you. Searching Google rendered many people asking essentially the same questions but I wasn't able to find specific answers to this scenario. Even Microsoft Premier Support had no idea.

I found registry entries in HKCU\Software\Microsoft\Windows NT\CurrentVersion\Windows Messaging Subsystem\Profiles that define the profiles. Most values are REG_BINARY, which require much reverse engineering, and many of the keys are unique to each user/computer, so a simple registry import would not be possible in many cases.

It's clear we need an API to properly update this system.

MAPI
I've been able to solve this problem with MAPI in native C++. Microsoft documents MAPI in MSDN, but sadly it is not nearly as concise and complete as, say, the .NET framework components. But still, there is just enough information to get your feet wet and experiment.

Fortunately, MSDN did publish an example solution that did some of what I wanted. The code is pretty ugly, but it had the necessary steps to get started.

Using These Tools
Download the executables from the attachments below.

Setting Contact Name Resolution Search Path
Usage: MAPIAddrListSearch "Address List A" [ "Address List B" ...]

Setting Default Address List
Usage: MAPIDefaultAddressList "Address List"

For both tools, the address list names are recognized from what is available in the Addressing dialog. Be sure to enclose the names with quotes if the names contain spaces. If the tool can't resolve the name, it won't make the configuration change for that name.

It may be necessary to restart Outlook after running these tools. In some cases, it caches old settings and other times not.

Compiling From Source
I've provided the attached solution with source so that one day another sysadmin could find this useful. The source is provided as a Visual Studio solution with separate solution files for 2005 and 2008 editions.

Note: I have only tested this code on Outlook 2003. It is unknown how it will behave with prior versions or with Outlook 2007. Please contact me if you have feedback on other versions.

Deployment Method
For deployment to a large group, you have a few viable options. However, what you probably don't want to do is have this run in a login script and update the user's settings every time. It would be friendly to set a baseline, but allow the user to modify to their liking later. A quick way to do this is with a login script via GPO or AD user profile that runs once and creates a check file indicating the settings were set. Then, on successive logins to skip the configuration if the check file exists. This is demonstrated in the SetOutlookDefaults.cmd script included in the download.

Be aware that these tools modify an existing MAPI profile. If the user is logging in on a PC for the first time, or has never opened Outlook or other MAPI-based mail apps, there will be no MAPI profile yet.