Change Student Primary SMTP Addresses in Hybrid Exchange with PowerShell
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.
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.
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.
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.
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.
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': $_" } }
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.
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.

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.




