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

Header: id,old_upn,new_upn,proxy[,new_primary]. Data does not leave your browser.

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

  1. Paste the CSV with header: id, old_upn, new_upn, proxy; optional new_primary (otherwise the new UPN becomes the primary address).
  2. Put the current proxyAddresses in the proxy column separated by ; (Get-ADUser -Properties proxyAddresses).
  3. 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

InputValue
User CSV
id,old_upn,new_upn,proxy
ayse.k,[email protected],[email protected],SMTP:[email protected];smtp:[email protected]
mehmet.c,[email protected],[email protected],SMTP:[email protected]
ali.y,[email protected],[email protected],SMTP:[email protected]
veli.y,[email protected],[email protected],SMTP:[email protected]

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

Related service: Microsoft 365, Azure, AWS and Google Cloud Services

Systems online tools · See all online tools