Adding Email Aliases in Active Directory

1.6K

To add an SMTP alias to a user in a Microsoft 365 (Exchange Online) tenant configured for Active Directory synchronization, you must add an additional SMTP address to the user’s proxyAddresses attribute in the on-premises AD.

Understanding the proxyAddresses Attribute

proxyAddresses attribute controls all email addresses (primary and aliases) for the user, and changes will sync to Exchange Online during directory synchronization.

When you use the Enable-Mailbox or New-Mailbox cmdlets to assign email attributes to a user in an on-premises Active Directory, only the primary email address is assigned by default.

For example, jbrion@theitbros.com. In order for a user to receive emails sent to an additional address, an alias address must be added for that user (for example, johh@theitbros.com). All emails sent to an alias email address will be delivered to the Exchange mailbox inbox specified as the primary address. Thanks to alternate email addresses (aliases), users can receive emails sent to multiple email addresses without requiring multiple mailboxes.

“Email address type update failed” error

The following error will appear when trying to add an alias to a user synchronized from an on-premises Active Directory (AD) to Microsoft 365:

Email address type update failed

Error executing request. An Azure Active Directory call was made to keep object in sync between Azure Active Directory and Exchange Online. However, it failed. Detailed error message: Unable to update the specified properties for on-premises mastered Directory Sync objects or objects currently undergoing migration. DualWrite (Graph)…

How to Add an Alias in Active Directory (GUI Method)

An administrator can add an alias to a user in on-premises AD using the Active Directory Users and Computers graphical MMC snap-in:

1. Open the ADUC console by running the command dsa.msc;
2. To show all the user attributes, enable the Advanced Features option in the View menu.

   

3. Open the properties of the user you want to add an alias to;
4. Navigate to the Attribute Editor tab;
5. Find and edit the proxyaddresses attribute. This multi-valued attribute contains primary and additional email addresses (aliases) associated with the user;
6. To add an email alias, specify it in the format smtp:alias@contoso.com, click Add and save the changes.
   

   

Important Notes: SMTP vs smtp Syntax

• The primary email address is always specified with the uppercase SMTP: prefix
• For secondary email addresses (aliases) use the lowercase smtp: syntax

How to Change the Primary SMTP Address

To change a user’s primary email address, you must update the proxyAddresses attribute and ensure that only one address uses the uppercase SMTP: prefix:

Note that when replacing the proxyAddresses attribute, you need to make sure you include all existing email addresses that should be retained. Keep in mind that any addresses omitted from the replacement list will be removed.

Set-ADUser jbrion -Replace @{
proxyAddresses=@(
"SMTP:newprimary@theitbros.com",
"smtp:oldaddress@theitbros.com",
"smtp:info@theitbros.com"
)
}

Note that only one address can use the uppercase SMTP: prefix because it defines the primary email address. For all additional email aliases you should use the lowercase smtp: prefix.

To promote an existing alias to the primary address, you need to change its prefix from smtp: to SMTP: and change the current primary address to lowercase smtp:.

Adding or Removing SMTP Aliases Using PowerShell

You can also add or remove SMTP aliases to a mailbox using PowerShell cmdlets from the Active Directory module.

Add a New Alias Address

Note that before adding a new alias, you need to check existing email aliases. To list all existing email addresses assigned to the user, run the command:

Get-ADUser jbrion -Properties proxyAddresses |
Select-Object -ExpandProperty proxyAddresses

The command mentioned above displays the primary SMTP address and all configured aliases (it helps you to avoid adding duplicate email addresses).

To add a new alias address, use the command:

Set-ADUser jbrion -Add @{proxyAddresses="smtp:info@theitbros.com"}

You can also bulk add email aliases. The following command adds SMTP aliases for multiple users from a CSV file in a single operation:

Import-Csv .\aliases.csv | ForEach-Object {

    $Alias = "smtp:$($_.Alias)"

    $User = Get-ADUser $_.SamAccountName -Properties proxyAddresses

    if ($User.proxyAddresses -notcontains $Alias) {
        Set-ADUser $_.SamAccountName `
        -Add @{proxyAddresses=$Alias}
    }
}

The example above assumes that all users listed in the CSV file already exist in AD.

Note that if an alias already exists in AD, Set-ADUser returns an error and the address is not added.

Here is an example of CSV file:

SamAccountName,Alias
jbrion,info@theitbros.com
jsmith,sales@theitbros.com

Remove an existing email alias

Set-ADUser jbrion -Remove @{proxyAddresses="smtp:info@theitbros.com"}

Synchronizing Alias Changes with Microsoft 365

Aliases added to a user in an on-premises Active Directory (AD) will appear in Exchange Online during the next synchronization cycle via Microsoft Entra Connect (formerly Azure AD Connect).

Or, you can force an immediate Entra ID sync:

Start-ADSyncSyncCycle -PolicyType Delta

Keep in mind that the Start-ADSyncSyncCycle cmdlet is available only on the server where Microsoft Entra Connect is installed.

You can use Get-ADSyncScheduler to view the sync schedule and check when the next sync cycle will occur:

Get-ADSyncScheduler

In case your organization uses Microsoft Entra Cloud Sync instead of Microsoft Entra Connect Sync, syncing schedules and management options may be different.

You can verify alias syncing with the command:

Get-EXOMailbox jbrion@theitbros.com |
Select-Object -ExpandProperty EmailAddresses

Keep in mind that the EmailAddresses property displays the primary SMTP address and all configured alias addresses assigned to the mailbox.

Also, the Set-Mailbox cmdlet from the Exchange Management Shell (EMS) module can be used to add user aliases:

Note. The following example applies only to mailboxes whose email addresses are managed in Exchange. For users synced from on-premises Active Directory, you should manage aliases through the proxyAddresses attribute in AD.

Set-Mailbox jbrion@theitbros.com `
-EmailAddresses @{Add="smtp:info2@theitbros.com"}

If you need to add an email alias ​​for a distribution list (DL) in an Exchange organization:

Set-DistributionGroup -Identity IT_alerts -EmailAddresses @{Add="smtp:alert@theitbros.com"}

Display all email addresses assigned to the distribution list:

Get-EXODistributionGroup it_alerts|select name,EmailAddresses

For users synced from on-premises AD, proxyAddresses must be managed in Active Directory. Keep in mind that changes you made directly in Exchange Online may fail/be overwritten during the next sync cycle.