Microsoft 365, AD and Windows · #30
Online UPN and SMTP Address Change Planner
Builds the proxyAddresses value for users' new UPN and primary address, keeps the old address as an alias and shows conflicts.
- Data is processed in your browser and not sent to a server
- Export: CSV
Tool
What does this tool do?
After a marriage, merger or domain change, UPN and email address change together. Not keeping the old address as an alias (lower-case smtp:) bounces incoming mail, and giving the same new address to two people breaks synchronisation. The tool returns the new proxyAddresses list, conflicts and the old values for rollback in one table.
How to use it
- Paste the CSV with header:
id, old_upn, new_upn, proxy; optionalnew_primary(otherwise the new UPN becomes the primary address). - Put the current proxyAddresses in the proxy column separated by
;(Get-ADUser -Properties proxyAddresses). - Press Calculate; download plan and rollback tables as CSV.
Fields
- User CSV
- Header: id,old_upn,new_upn,proxy[,new_primary]. Data does not leave your browser.
Worked example
| Input | Value |
|---|---|
| User CSV | |
Expected result: Ayşe's new list is SMTP:[email protected];smtp:[email protected];smtp:[email protected]; Mehmet's old domain stays as an alias; ali.y and veli.y both get the same new UPN ([email protected]) and are both red.
There must be exactly one upper-case SMTP:, the primary address; lower-case smtp: entries are aliases. The Veli Yılmaz row is most likely a copy-paste error; if not fixed before sync, Entra Connect quarantines one of the objects.
Method and assumptions
The new primary address is new_primary, or new_upn if absent, written with SMTP:. Other addresses from the old proxyAddresses and the old UPN (if missing) are added as smtp: aliases; no address is written twice (case-insensitive).
Conflicts: the same new UPN on more than one row; the new primary address already in another row's proxyAddresses; invalid address format.
Using the result and troubleshooting
In hybrid environments make the change in on-premises AD (UPN and proxyAddresses) and wait for Entra Connect sync. For cloud-only accounts use Set-Mailbox -EmailAddresses in Exchange Online and Graph for the UPN.
A UPN change affects the OneDrive URL and sessions in some apps; inform users. The rollback table contains each user's old UPN and proxy value.
Limits and common mistakes
- It does not connect to the directory; it only finds conflicts within this CSV. Check conflicts against the whole tenant in Exchange.
- Non-SMTP entries (x500, sip:) from the proxy column are not carried into the new list; add them separately.
Frequently asked questions
Why keep the old address as an alias?
People's address books and autocomplete contain the old address; without the alias that mail bounces with an NDR.
Related tools and service
- AD and Microsoft 365 Username GeneratorGenerates collision-free UPN and sAMAccountName candidates from a list of names; converts Turkish and German characters correctly.
- Entra Connect Sync Inventory DiffMatches on-premises AD and Entra user lists by source anchor; shows attribute differences and unmatched objects.
Related service: Microsoft 365, Azure, AWS and Google Cloud Services