Others

Change Student Primary SMTP Addresses in Hybrid Exchange with PowerShell

John WilsonJohn Wilson Nov 14, 2026 868 views

Question details

Update incorrect primary SMTP addresses for synchronized student accounts in an on-premises Active Directory OU.

Product
Microsoft Exchange Server and Active Directory
Device & OS
not provided
Scenario
A hybrid Exchange organization needs to update student mailbox addresses in the on-premises directory so the changes can synchronize to Exchange Online.
Observed behavior
Synchronized student accounts show incorrect primary SMTP addresses.
Before you start

Confirm that the student accounts are remote mailboxes managed by on-premises Exchange, and identify the Student OU's distinguished name. Prepare a CSV mapping each account's sAMAccountName to its intended address, and check that the addresses comply with your policy and are unique across the organization.

Solution 1Recommended

Preview and update student remote mailbox addresses

Use on-premises Exchange Management Shell to update remote mailboxes in the Student OU while preserving Exchange's management of mailbox attributes.

Use Set-RemoteMailbox for remote mailboxes rather than editing proxyAddresses directly. The script below processes only CSV entries whose accounts are found in the specified OU. It does not check address uniqueness across the organization, so perform that check before applying changes.

Check your email address policy before changing addresses; an applicable policy may overwrite a manually assigned address. The script does not change policy settings.

1
Prepare the address mapping

Create a CSV file such as C:\Temp\student-addresses.csv with the headers SamAccountName and NewPrimarySmtp. Add one row per student, and replace the example path and OU distinguished name in the script with your own values.

2
Open the management shell

Open Exchange Management Shell in the on-premises environment with an account authorized to manage remote mailboxes. Make sure the Active Directory PowerShell module is available.

3
Preview the changes

Run the following script with -WhatIf left in place. Review its output for skipped accounts, invalid addresses, and the proposed mailbox changes: Import-Module ActiveDirectory $ou = 'OU=Students,DC=example,DC=com' $rows = Import-Csv 'C:\Temp\student-addresses.csv' $users = @{} Get-ADUser -Filter * -SearchBase $ou | ForEach-Object { $users[$_.SamAccountName] = $_ } $seen = @{} foreach ($row in $rows) { $name = $row.SamAccountName.Trim() $address = $row.NewPrimarySmtp.Trim() if (-not $name -or -not $address -or $address -notmatch '^[^\s@]+@[^\s@]+\.[^\s@]+$') { Write-Warning "Invalid mapping for '$name'; skipped." continue } if ($seen.ContainsKey($name)) { Write-Warning "Duplicate account '$name'; skipped." continue } $seen[$name] = $true if (-not $users.ContainsKey($name)) { Write-Warning "Account '$name' not found in the OU; skipped." continue } try { $mailbox = Get-RemoteMailbox -Identity $users[$name].DistinguishedName -ErrorAction Stop Set-RemoteMailbox -Identity $mailbox.Identity -PrimarySmtpAddress $address -WhatIf -ErrorAction Stop } catch { Write-Warning "Could not process '$name': $_" } }

4
Apply and verify

After resolving warnings and checking address uniqueness, remove -WhatIf from the Set-RemoteMailbox line and run the script again. Use Get-RemoteMailbox -Identity '<account>' | Format-List PrimarySmtpAddress,EmailAddresses to verify on-premises values, then check the mailbox in Exchange Online after directory synchronization.

For non-remote-mailbox objects: This script skips accounts that Get-RemoteMailbox cannot find. Other Active Directory objects may require a different approach; review their object type and attribute requirements before using Set-ADUser.
Free Microsoft Office alternative

Review student address mappings with WPS Office

WPS Office is a free, lightweight alternative for reviewing address-mapping files in a familiar spreadsheet interface. Its Microsoft Office format compatibility makes it easy to move existing files; it does not manage Exchange or run the PowerShell update.

Review student account and SMTP address mappings in a spreadsheetOpen and edit Microsoft Excel XLSX filesUse a familiar interface for an easy transition from Microsoft OfficeWork with a free, lightweight office suite
microsoft office alternative - wps office

Frequently Asked Questions

Why use Set-RemoteMailbox instead of editing proxyAddresses directly?

For an on-premises-managed remote mailbox, Set-RemoteMailbox is the Exchange management cmdlet for changing its properties. Direct attribute edits can bypass Exchange validation and require careful handling of existing proxy addresses.

How can I preview the bulk update without changing accounts?

Leave -WhatIf on the Set-RemoteMailbox command and run the script in Exchange Management Shell. Review the proposed changes and warnings before removing -WhatIf.

Will the new address appear in Exchange Online immediately?

Not necessarily. Verify the on-premises value with Get-RemoteMailbox, then allow directory synchronization to run before checking the mailbox in Exchange Online.

What if an email address policy changes the address back?

Review the mailbox's applicable on-premises Exchange email address policy before applying manual changes. Adjust the policy or mailbox policy settings only in accordance with your organization's requirements.

Does the script prevent duplicate SMTP addresses across the organization?

No. Check the proposed addresses against existing recipients, including relevant cloud recipients, before applying the update. The script only detects duplicate account names in the CSV.