Exchange script: Fix broken migrated email addresses by splicing the historical LEDN in as a new X500 address

1/7/2018: I was working on a mail migration and needed to dust off and use this script, so I figured I'd go ahead and post it.

The underlying purpose for this script is, to workaround and suppress...
    # 550 5.1.1 RESOLVER.ADR.ExRecipNotFound; Not found'
... errors for users replying to email that has been migrated from an external mail system.

Short form of the issue is that the migrated email (and Outlook Personal-Contacts) contain addresses stored in old-school X500 format (termed a LegacyExchangeDN). And unfortunately these addresses aren't functional anywhere except the source mail system.

But, there's a way around the issue: If you "add" the broken X500/LEDN value from the old  system into the moved user's Exchange EmailAddresses list, that patched-in addresses will provide a 'shim' for delivery lookups that permits Exchange to resolve the address to the proper migrated user mailbox.

And that's where this script comes in: It takes a .csv file containing each migrated-user's 'WindowsEmailAddress' & 'LegacyExchangeDN' values exported from the migration source mail system, and splices the old LegacyExchangeDN value into the existing new mailbox EmailAddresses property.


Note: If you find yourself with these errors and you no longer have access to the original source mail system, you can approximate the necessary LEDN value to be added by examining the bounces generated by these bad addresses - the appropriate missing value will be right in the middle of the bounce:

IMCEAEX-_O=COMPANY_OU=EXCHANGE+20ADMINISTRATIVE+20GROUP+20+28FYDIBOHF23SPDLT+29_CN=RECIPIENTS_CN=[recipientname]NAME@DOMAINcom
    # 550 5.1.1 RESOLVER.ADR.ExRecipNotFound; Not found

Hint: It's the entire string after 'IMCEAX-'  

Notes and instructions for use of the script are included in the help block at the top of  the script.

This is pretty simple stuff. There's already a lot of commonly-available sample code already out there. The only real additions I make to the process are:

•     My script runs more error checking and validation around the changes (less risk of error).
•     I dump output details back for verification and loggging (to provide a good audit trail of the modifications).
•     The script supports a -whatif param to let you run test passes (so you can see what changes will occur, before executing the updates).
•     And it runs natively in Exchange Mgmt Shell. Most other folks leverage the AD powershell module's set-aduser command to do the update. I don't mind using ADMS, but using Exchange gives me more detail and better control (and avoids some of the annoying syntax inconsistencies it comes with ;P).

The Gist below has the core working bit of the larger script: