Every Microsoft 365 mailbox carries a stack of addresses that rarely gets audited. You see the primary SMTP address in the admin center, maybe a couple of legacy addresses from an old domain migration, and often a few entries nobody remembers adding. Those hidden entries are Microsoft 365 email aliases, and they sit in the proxyAddresses collection of the Exchange Online mailbox. Get one property wrong in PowerShell and you can wipe all of them in a single command.
That is the trap this tutorial addresses. Running Set-Mailbox -EmailAddresses with a plain string does not append an alias, it overwrites the whole list. The correct pattern uses hash-table syntax, @{Add=’smtp:new@contoso.com’}, which tells Exchange to merge the new entry into what already exists. The same logic applies when you remove an address with @{Remove=…} or replace the primary address with @{Replace=…}. Once you understand why the hash table works, the rest of alias management becomes routine.
The steps below cover connecting to Exchange Online, reading current proxy addresses, adding and verifying a new alias, sending from an alias in Outlook, and cleaning up without collateral damage. They also cover the errors that show up most often: duplicate proxy addresses, missing smtp: prefixes, and permission problems on shared mailboxes. Expect new aliases to take up to 24 hours before mail flow settles, and remember that Microsoft limits how frequently users can add aliases, so batch your changes rather than looping one address at a time.
What an Email Alias Is in Outlook, Outlook.com, and Microsoft 365
An email alias is an additional address that delivers mail into an existing mailbox. The word gets used for two different mechanisms, and mixing them up is the most common reason a PowerShell command does something unexpected. The tutorial that follows deals with the Microsoft 365 flavor, so it is worth pinning down the vocabulary first.
On Outlook.com, an alias attaches to a Microsoft account. You can create one at account.microsoft.com, and it becomes a full alternate email address you can sign in with. Every alias funnels into the same inbox, so mail sent to any of them lands in one place. Microsoft caps how many you can hold (10 per year, 50 total at the time of writing) and how often you can add them. Sign-in behavior has a wrinkle: security codes are sent to the primary username, not to the alias you just created, so an alias you cannot receive mail at yet is a poor recovery option. This is consumer plumbing, managed through a web page, with no PowerShell surface at all.
In Microsoft 365, an alias attaches to a mailbox inside an Exchange Online organization. Each address lives as an entry in the mailbox’s proxyAddresses attribute, which is what Get-Mailbox reports back as EmailAddresses. Exactly one entry carries the uppercase SMTP: prefix and is the primary address; every other entry uses lowercase smtp: and is a secondary email address. A Microsoft 365 business plan allows roughly 300 addresses per mailbox, which is why organizations routinely stack role addresses, legacy domains, and vendor spellings onto a single user.
The two use cases the rest of this guide serves are straightforward. The first is to create email alias entries in bulk, for a domain migration or a rebrand, without touching the admin center one mailbox at a time. The second is to send from an alias, so replies leave with the address the recipient actually wrote to. Sending from a secondary address requires an administrator to enable it once via Set-OrganizationConfig -SendFromAliasEnabled $true; until then the alias receives mail but cannot originate it.
Two constraints shape every command in the following sections. An alias must use a domain added to Microsoft 365 and verified in the tenant, so a typo in the domain produces a validation error rather than a working address. And new aliases can take up to 24 hours to work across the service, so a send test that fails in the first hour is not necessarily a broken command.
Connecting to Exchange Online PowerShell and Reading Current Proxy Addresses
Before you touch a single alias, get a clean read of what is already on the mailbox. Most broken alias lists come from skipping this step. The inspection takes two minutes and tells you which addresses are primary, which are secondary, and which domains are already in play.
Start with the module. On Windows PowerShell 5.1 or PowerShell 7, run Install-Module -Name ExchangeOnlineManagement -Scope CurrentUser -Force once per machine, then Import-Module ExchangeOnlineManagement in every new session. The v3 module uses REST and does not require Basic authentication, so it works on tenants where Basic auth is disabled. If you are on an older v2 install, remove it first with Uninstall-Module ExchangeOnlineManagement to avoid command collisions.
Connect with Connect-ExchangeOnline -UserPrincipalName admin@contoso.com. Use an account that holds the Recipient Management role or higher. Delegated accounts without that role will connect fine and then fail on every Set-Mailbox call, which produces confusing permission errors later. For scripted runs, add -ShowBanner:$false to keep output clean.
Now read the mailbox. The command below returns every address in the proxyAddresses collection:
Get-Mailbox -Identity jsmith@contoso.com | Select-Object -ExpandProperty EmailAddresses
Read the output carefully. The entry prefixed SMTP: in uppercase is the primary address and the one that appears in the From field by default. Entries prefixed smtp: in lowercase are secondary addresses. Entries with X500: or sip: are legacyExchangeDN and SIP values that Exchange or Teams manages, so leave them alone. A quick count helps you confirm nothing was lost after a change:
(Get-Mailbox -Identity jsmith@contoso.com).EmailAddresses.Count
To check several mailboxes at once, pipe from Get-Mailbox into a formatted table:
Get-Mailbox -ResultSize Unlimited | Select-Object DisplayName, @{n=’Aliases’;e={($_.EmailAddresses | Where-Object {$_ -clike ‘smtp:*’}).Count}}
Note the -clike operator with a case-sensitive comparison. It matches only lowercase smtp: entries, which isolates the secondary addresses from the primary SMTP: one. That distinction matters in the next section, where a single prefix determines whether you add an alias or overwrite the primary address.
Save the current list to a file before making changes. Get-Mailbox jsmith@contoso.com | Select-Object -ExpandProperty EmailAddresses | Out-File C:\temp\jsmith-aliases.txt gives you a rollback reference if an edit goes wrong. If the mailbox holds an alias on a domain you do not recognize, confirm that domain is verified in Microsoft 365 before adding anything new to it.
The @{Add=…} Syntax: Why Set-Mailbox Replaces the Whole Alias List
The single most common way administrators destroy a working mailbox configuration is by treating -EmailAddresses like a property that grows. It does not grow. When you pass a value to Set-Mailbox -EmailAddresses, Exchange Online treats that value as the complete, authoritative list of proxy addresses for the object. Whatever you supply becomes the new proxyAddresses collection. Anything not in your command is gone.
This is why the following line is dangerous:
Set-Mailbox -Identity j.smith@contoso.com -EmailAddresses “smtp:jsmith@contoso.com”
That command does not add an alias in Outlook.com. It replaces the entire multi-valued attribute with a single secondary address. The primary SMTP address is stripped of its SMTP: uppercase prefix, every existing SMTP alias disappears, and mail flow to those addresses stops immediately. No prompt, no confirmation, no undo. If the mailbox was reachable through five addresses used by different business units, four of them now bounce.
The safe form uses a hash table with an operation key. PowerShell merges the operation against the existing collection instead of assigning over it:
Set-Mailbox -Identity j.smith@contoso.com -EmailAddresses @{Add=’smtp:jsmith@contoso.com’}
Read the pieces carefully. The @{Add=…} block tells the cmdlet to perform a collection operation. The value inside is a string prefixed with smtp: in lowercase, which marks it as a secondary address. Uppercase SMTP: designates the primary address, and only one per mailbox can carry it. Omit the prefix entirely and Exchange rejects the value or stores something you did not intend.
Multiple aliases go in one array, and the whole set is added atomically:
Set-Mailbox -Identity j.smith@contoso.com -EmailAddresses @{Add=’smtp:jsmith@contoso.com’,’smtp:john.smith@contoso.com’,’smtp:j.smith@fabrikam.com’}
Two constraints apply. Each alias must use a domain already accepted in the tenant, otherwise the write fails with a domain validation error. And every new alias is subject to the tenant-wide alias frequency limit, so bulk scripts that add dozens of addresses in a tight loop will start returning throttling errors rather than results.
Rule of thumb: never type a bare string after -EmailAddresses on a live mailbox. Use @{Add=…} to append, @{Remove=…} to delete, and @{Replace=…} only when you genuinely intend to redefine the full list. The same behavior applies to Set-DistributionGroup and Set-MailUser, so the habit pays off across every recipient type in Exchange Online.
Step-by-Step: Creating, Verifying, and Sending From a Microsoft 365 Email Alias
Adding, confirming, and testing the new address
Before running anything, confirm the alias domain is one Microsoft 365 actually accepts. An alias must use a domain added to Microsoft 365 and verified in the tenant, otherwise Set-Mailbox fails with a domain validation error. Run Get-AcceptedDomain and pick a routed domain, not the onmicrosoft.com default unless you intend it.
The command below adds one secondary SMTP address to an Exchange Online mailbox. Note the lowercase smtp: prefix for secondary addresses and the uppercase SMTP: prefix reserved for the primary address. A mailbox carries exactly one primary SMTP entry.
Set-Mailbox -Identity jane.doe@contoso.com -EmailAddresses @{Add=’smtp:j.doe@contoso.com’,’smtp:jane@fabrikam.com’}
Then verify. The hash-table operation returns nothing on success, so the only reliable confirmation is a read:
Get-Mailbox -Identity jane.doe@contoso.com | Select-Object -ExpandProperty EmailAddresses
Compare the output against what you saw before the change. Every prior entry should still be present plus the new ones. If the list shrank, you overwrote the collection rather than appended to it, and the missing addresses need restoring from your notes or a backup export.
Mail flow to the new address typically starts within minutes, but new aliases can take up to 24 hours to work across all routing paths, especially after directory replication. Send a test message from an external account and check message trace if nothing lands.
Sending from the alias is a separate switch. An administrator enables sending from aliases via Set-OrganizationConfig -SendFromAliasEnabled $true. After that, Outlook on the web and the new Outlook for Windows show the alias in the From dropdown when composing. Classic desktop Outlook does not expose the alias in From until the mailbox is re-synced; restarting the client or rebuilding the profile resolves most cases. In Outlook.com, aliases linked to a Microsoft account behave differently: they share the inbox, and you select the alias as the sender in the compose window without any PowerShell step.
Work through this checklist to close the loop:
- Confirm the domain with Get-AcceptedDomain.
- Add the alias with @{Add=…} using the correct smtp: prefix.
- Re-read EmailAddresses and diff against the previous list.
- Enable SendFromAliasEnabled at the organization level if needed.
- Send a test message from an external mailbox and from the alias itself.
Removing Aliases Safely and Troubleshooting Common Set-Mailbox Errors
Deleting an alias is the same hash-table pattern in reverse. Passing @{Remove='smtp:old@contoso.com'} to Set-Mailbox -EmailAddresses strips exactly that entry and leaves every other proxy address intact. The prefix matters: the value must match the stored string byte for byte, including the lowercase smtp: for a secondary address or uppercase SMTP: for the primary. If you only know the address and not its casing, pull the list first with (Get-Mailbox user@contoso.com).EmailAddresses and copy the entry verbatim.
Removing the primary SMTP address is refused outright. Exchange Online requires one uppercase SMTP: value per mailbox, so promote a different alias first, then remove the old one in a second command. Removing an alias also removes the ability to receive mail at that address immediately; senders get an NDR, and the address cannot be re-added to another mailbox until replication completes. New aliases can take up to 24 hours to work across the tenant, and removal follows a similar propagation pattern, so do not treat a failed delivery in the first hour as evidence the command did not run.
The errors you will actually hit, and what each one means:
- “The proxy address smtp:x@contoso.com is already being used by…” Another recipient, a distribution group, or a soft-deleted mailbox still holds the address. Find the owner with
Get-Recipient -ResultSize Unlimited | Where-Object {$_.EmailAddresses -match 'x@contoso.com'}and clear it there. - “The proxy address is not valid” The
smtp:prefix is missing or the domain is not an accepted domain in the tenant. An alias must use a domain added to Microsoft 365; check withGet-AcceptedDomain. - “Access denied” or “Insufficient permissions” The account lacks the Mail Recipients role. Membership in Recipient Management is the usual fix; application-based auth needs the
Exchange.ManageAsApppermission granted and consented. - Silent success but no mail flow The address was added to the wrong object, or a transport rule rewrites the recipient. Confirm with
Get-Mailbox, then run a message trace on a test message.
One habit prevents most of these failures: run the command with -WhatIf first. It prints the resulting proxy address collection without writing anything, so a missing prefix or a duplicate shows up before it becomes a support ticket.
Before you close the session, run one last Get-Mailbox -Identity user@domain.com | Select-Object -ExpandProperty EmailAddresses and compare the output against the list you captured in step 2. The count should equal the old total plus the addresses you added, minus anything you removed. If the number dropped, a plain string assignment overwrote the collection somewhere along the way, and the missing smtp: entries have to be rebuilt from your saved export. Keep that export until mail flow to the new address is confirmed, since new aliases can take up to 24 hours to work and a rollback is faster with the original values on hand.
A practical next step is to script the whole routine for one pilot mailbox and run it against a test account first: read the current proxyAddresses, build the @{Add=’smtp:newalias@yourdomain.com’} hash table, apply it with Set-Mailbox, then verify with Get-Mailbox. Once that loop behaves predictably, extend it to a CSV of users, but respect the alias frequency limit Microsoft enforces per user and remember that an alias must use a domain added to Microsoft 365, so check accepted domains before the bulk run. If you also need people to reply from the new address rather than just receive on it, confirm with your administrator that sending from aliases is enabled via Set-OrganizationConfig -SendFromAliasEnabled $true, then send a test message from Outlook to prove the From field exposes the alias.