📧 Recipe · Exchange & Email

Add an Email Alias (Proxy Address) to a Mailbox via Microsoft Graph

Add a secondary SMTP address to a Microsoft 365 mailbox so it can receive mail at multiple addresses

Complexity

Beginner

Impact

mail-flow + identity + low-risk + reversible

Context

Why This Matters

Email aliases (also known as proxy addresses) let a single mailbox receive mail at more than one address without creating additional licensed users. Common scenarios include:

A shared mailbox like info@contoso.com that also needs to accept mail for contact@contoso.com.
Adding a personalized alias (e.g. firstname.lastname@contoso.com) alongside a standard flast@contoso.com UPN.
Absorbing mail flow for a newly-acquired domain into an existing mailbox.

In Microsoft 365, aliases are stored on the user object as the proxyAddresses multi-valued attribute. Each entry is prefixed with SMTP: (uppercase, for the primary address) or smtp: (lowercase, for secondary aliases).

This recipe shows how to safely add a new alias without accidentally removing existing ones or demoting the primary address.

Expected Outcomes

After following this recipe you will have:

Added the new alias as a lowercase smtp: entry in the mailbox's proxyAddresses collection.
Preserved the existing primary (SMTP:) address and all other aliases.
Verified the alias is registered on the user object and ready to receive mail (typically within a few minutes).

Risks & Considerations

Warnings & gotchas

The domain must be verified in your Microsoft 365 tenant before it can be used in a proxy address. Unverified domains will be rejected by Graph.
Case matters. Only one entry should begin with uppercase SMTP: — that is the primary reply address. Adding a second uppercase entry, or changing case accidentally, will change the reply-from address for the mailbox.
Uniqueness is enforced tenant-wide. An alias cannot be assigned if the same SMTP address is already in use on any other user, group, or mailbox.
PATCH replaces the entire array. When updating proxyAddresses via Graph, always send the full existing list plus the new entry — sending only the new entry will wipe existing aliases.
If the mailbox is synced from on-premises Active Directory, changes made in the cloud will be overwritten by AD Connect. Make the change on the on-prem user's proxyAddresses attribute instead.
Propagation to Exchange Online directory can take a few minutes. Test delivery only after waiting.

Required Permissions

Permission	Why It's Needed
User.ReadWrite.All	Required to read and update the proxyAddresses attribute on user objects.
Directory.ReadWrite.All	Alternative, broader permission that also permits modifying directory objects including user proxy addresses.
Exchange Administrator or Global Administrator role	Required when using the Exchange admin center or Exchange Online PowerShell (Set-Mailbox) instead of Graph.

The fastest way to get this done — just ask Dex. Copy the prompt below and paste it into your Dex conversation.

For IT Admins

Paste into Dex CoAdmin

Add the alias {new_alias} to the mailbox {mailbox_upn}. Preserve the existing primary SMTP address and all current aliases, verify the update, and confirm no conflicts exist in the tenant.

Try in Dex CoAdmin

For End Users

How an employee would ask Dex for help

Can you set up my mailbox so it also receives email sent to {new_alias}?

Try in Dex Playground