Anyone who has participated in migrations or transitions to Exchange is probably familiar or had to work around potential issues caused by the nickname cache. A “cache,” also known by its file extension, NK2 in older Outlook clients, is a convenience feature in Outlook and Outlook on the web (OWA). It lets users pick recipients from a list of frequently-used recipients. This list is displayed when the end user types in the first few letters:
This information can be stored in multiple locations, depending on the client used. Before Outlook 2010, this information was stored in local NK2 files. For Outlook 2010 and up, this information is stored in a hidden item in your mailbox. This item, the AutoComplete Stream, will be cached locally by Outlook for performance reasons. Outlook on the web (OWA) on the other hand, utilizes its own caching mechanism, storing this recipient information in a different part of your mailbox. In addition, other recipient information not directly stemming from addressing is stored as well, such as the Suggested Contacts folder.
The issue arises when mailboxes are moved to other organizations such as during a merger or acquisition, or other form of cross-Exchange organization or tenant mailbox move. When using an Exchange-related recipient, Outlook will store the underlying address that is used by Exchange – the infamous X500 legacyExchangeDN, which looks like /o=Organisation/ou=Administrative Group/cn=Recipients/cn=Username – together with the recipient. When picking an address from the list, you are effectively picking the associated x500 address.
Now, because AutoComplete and other recipient caches are static, this x500 address may become invalid at some point. That is, unless it has been applied to the migrated mailbox and thus can be resolved in the new environment. For example, in Exchange hybrid deployments, Active Directory Connect (DirSync) will take care of properly propagating this attribute, stamping it as x500 address on the proxyAddresses attribute.
However, not all migrations or M&A scenarios allow for this information to retained, it might get overlooked, or perhaps organizations wish to start with a clean slate. In that case, zapping this cached information on the back-end might be an option, as opposed to instructing end users to remove entries from the picker. Here is where the Clear-AutoComplete script comes in, which might support those scenarios. Depending on the scenario, this script can zap the desired information, clearing cached information with potentially outdated information. Downside is that end users will have to repopulate their recipient pick lists, which is perhaps a small price when compared to the potential non-deliveries and support calls that might be the result of not clearing this information.
Before we talk about using the script, first a bit on the various caching mechanisms . . . .
The autocomplete stream contains information from previously used recipients from Outlook (for Desktop). The list contains address information such as SMTP or LegacyDN addresses and is limited to 1,000 most-recently used entries. The information is stored in the so-called folder-associated information (FAI) table of your Inbox, which is a hidden folder. FAI entries can be inspected using utilities like MFCMAPI or EWS Editor, like in the screenshot below, showing the AutoComplete Stream using MFCMAPI.
As indicated, the autocomplete stream is stored an item of message class IPM.Configuration.Autocomplete. The entries themselves are stored in the property PR_ROAMING_BINARYSTREAM (pidTagRoamingBinary, tag 0x7C09000A) which, as the name implies, is in binary format. However, you can inspect the information in a more comprehensible format using MFCMAPI. In MFCMAPI, open up the PR_ROAMING_BINARYSTREAM property of the IPM.Configuration.Autocomplete item using the Smart View structure definition Nickname Cache.
Outlook will only retrieve the autocomplete stream when addressing its functionality, such as entering a recipient in the To section when composing an e-mail. Any updates to the autocomplete stream will not immediately be written back to the FAI item, but will be saved when Outlook is closed. Because of this, Outlook must be closed when making changes to the autocomplete stream in the mailbox, or Outlook may overwrite it with its own cached copy.
Note that Outlook caches autocomplete streams locally in %userprofile% under \AppData\Local\Microsoft\Outlook\RoamCache. The files are named Stream_Autocomplete*.dat, with only one .dat file per configured account. These files are used when running Outlook in Cached Mode and serve as a storage location for updating the FAI item.
End users can reset the nickname cache from Outlook via File > Options > Mail > Send Messages using the button Empty Auto-Complete List. Alternatively, the autocomplete list may be reset using a switch when starting Outlook, e.g. outlook.exe /CleanAutoCompleteCache.
Outlook on the web (OWA) caches recently used recipient information. Unfortunately, it does not share this information with Outlook. OWA stores its autocomplete stream information in the FAI table of the root folder of your mailbox, in an IPM.Configuration.OWA.AutocompleteCache message class item. In the image below, an example is shown from the associated contents of the root container of a mailbox, using MFCMAPI.
The autocomplete stream is stored in the item of message class IPM.Configuration.OWA.AutocompleteCache, but when accessing item through Exchange Web Services, you need to drop the IPM.Configuration prefix. The entries themselves are stored in the property PR_ROAMING_XMLSTREAM (pidTagRoamingXmlStream, tag 0x7c080102) which, as the name implies, is stored in XML format (in the screenshot the stream does not contain any entries).
Users using the Light version of Outlook WebApp can also reset OWA's recipient cache via Options > Messaging > Clear Most Recent Recipients List.
The Suggested Contacts folder is created by Outlook. It is a folder to which contact objects will be added for each recipient used to send messages to, but that are not present in your Contacts folder. Like ordinary address books, Suggested Contacts is used as an additional address book for looking up recipients.
Note that unlike autocomplete, Suggested Contacts entries cannot be searched when typing the first few characters of a recipient. Also, users cannot manually add entries to the Suggested Contacts.
The Recipient Cache folder got introduced with Exchange 2013. It is a non-visible, well-known folder that sits below the Contacts folder, as shown in the MFCMAPI screenshot below. The specific purpose of the Recipient Cache folder is not documented. However, it does contain cached recipient information.
The Clean-AutoComplete script is straightforward. It uses Exchange Web Services, and requires the EWS Managed API (how to). The mailbox can be hosted in Exchange on-premises or Exchange Online. The Clear Autocomplete script itself can be downloaded from GitHub. It can use Basic Authentication or Modern Authentication (OAuth2, requiring the NuGet package Microsoft.Identity.Client). For the latter, you need to register an application in Azure AD, configure it with sufficient permissions to access the mailboxes, and provide admin consent.
Usage of Clean-AutoComplete.ps1 is as follows:
Clear-AutoComplete.ps1 [-Identity] String [-Server <String>] [-Impersonation] [-Credentials<PSCredential>] [[-CertificateThumbprint <String>] [-CertificateFile <String> [-CertificatePassword ] <SecureString> [-Secret <SecureString>]] -TenantId <String> -ClientId <String>] [-Type <Array>] [-Pattern <String>] [-WhatIf] [-Confirm]
Note that you can only specify one authentication method. So, when specifying Credentials, you cannot specify one of the modern authentication parameters such as CertificateFile. Also, when specifying CertificateThumbprint, you cannot – and need not - specify Secret nor Credentials.
For example, assume you have created a self-signed certificate to use with the script. You want to use OAuth2, and have registered an application for it in Azure AD and configured sufficient permissions such as Exchange.ManageAsApp. To remove the fabrikom.com entries from the OWA cache, you can run the script as follows:
.\Clean-AutoComplete.ps1 -Identity email@example.com -Server outlook.office365.com -TenantId <TenantID> -ClientId <AppId> - Secret (ConvertToSecureString -String 'MySecret' -Force -AsPlainText) -Type OWA -Pattern '*@contoso.com' -Verbose
We added the Verbose switch to display additional information during processing. Also, you can suppress the confirmation prompt using the common -Confirm:$False.
Accelerate Your Transition and Reduce Risk with ENow’s Mailscape!
Monitoring every key aspect at every single turn may seem impossible, which is why it is always safer, smarter, and less complicated if you find the right systems management tool. But why pay for an expensive solution that only assists you during your migration and then becomes obsolete? Why not purchase an affordable, intuitive software that can help during each phase of your migration and beyond? Enow's Mailscape is an affordable, intuitive and award-winning software solution that can help during each phase of your migration and, more importantly, help you beyond your migration.
Access your free 14-day trial of ENow’s Office 365 Monitoring and Reporting solution today!
I'm a Microsoft 365 Apps and Services MVP, with focus on Exchange, Identity, and an affection for PowerShell. I'm is a consultant, publisher of EighTwOne, published author, and speaker.