When Set-Mailbox has no PrimarySmtpAddress in Exchange Online
The same command works for one admin and does not exist for another. Once you know why, there are two reliable ways to set a primary address.
You want to promote an existing alias to be a mailbox''s primary address. Every result tells you the same thing:
Set-Mailbox -Identity someone@example.com -PrimarySmtpAddress new@example.comAnd Exchange Online replies:
Set-Mailbox : A parameter cannot be found that matches parameter name 'PrimarySmtpAddress'.Why this wastes your afternoon
The error is a parameter binding failure, which reads like a client problem. So you check you are connected. You reconnect. You reinstall the module. None of it helps, because nothing is broken.
The modern module builds each cmdlet''s parameter set from your assigned roles. Parameters you are not entitled to use are not hidden behind a permissions error, they are absent from the cmdlet altogether. So the same command, in the same module version, genuinely does not exist for one connection and works perfectly for another.
We have now seen both. On one tenant the parameter was missing and WindowsEmailAddress was the only route. On another, connected with broader rights, Set-Mailbox -PrimarySmtpAddress ran across eight mailboxes and set every primary correctly in a single pass.
If a parameter someone else uses successfully does not exist for you, that is a permissions signal rather than a version difference. Do not go looking for the wrong module.
See what your connection actually offers, and what roles you hold:
Get-ManagementRoleAssignment -RoleAssignee you@example.com -Delegating $false |
Select-Object -ExpandProperty Role | Sort-Object -UniqueIf Mail Recipients is in that list, permissions are not your problem. And you can see exactly what the cmdlet does offer:
(Get-Command Set-Mailbox).Parameters.Keys | Sort-ObjectWhat actually works
If the parameter is available to you, it is the cleanest option. It adds the address, promotes it, and demotes the previous primary to an alias in one operation:
Set-Mailbox -Identity someone@example.com -PrimarySmtpAddress new@example.comIf it is not available, this does the same job:
Set-Mailbox -Identity someone@example.com -WindowsEmailAddress new@example.comOn a cloud mailbox with no email address policy applied, setting WindowsEmailAddress promotes that address to primary. One command, and it leaves the rest of the address collection alone.
Verify by case, not by trusting the command:
Get-Mailbox someone@example.com | Format-List PrimarySmtpAddress, Alias, EmailAddressesExchange marks the primary with an uppercase SMTP: prefix and aliases with lowercase smtp:. Exactly one entry should be uppercase.
Do not try -EmailAddresses @{add="SMTP:new@example.com"}. Adding an address never promotes it, and the uppercase prefix makes it reject with a complaint about multiple primary SMTP addresses.
The fallback, and its hazard
If WindowsEmailAddress does not take, replace the whole collection at once, which does work where the add form fails:
Set-Mailbox -Identity someone@example.com -EmailAddresses `
"SMTP:new@example.com","smtp:old@example.com"Read the existing collection first and carry over every entry, including any X500:, SIP: or SPO: addresses. Dropping an X500 address silently breaks replies from anyone with the old address cached in their mail client, and that surfaces weeks later as a delivery failure nobody can explain.
The related confusion: alias is not the address
The admin centre presents these as one thing and they are not.
- The alias, or mail nickname, is the bare name and must be unique across the whole tenant. If
hellois taken, your new mailbox becomeshello1. - The primary SMTP address is a full address.
hello@one-domain.comandhello@another-domain.comdo not clash.
So a mailbox can quite happily keep the alias hello1 while sending as hello@yourdomain.com. Being refused the name you wanted at creation does not mean you cannot have the address.
Need help with any of this?
These notes are free and always will be. If you would rather someone just set it up, or you are stuck on something similar, get in touch at hello@opsira.io.