Adding Proxy Addresses in Active Directory with PowerShell

Overview of Proxy Addresses

Here’s a quick overview of how proxy email addresses function in Active Directory:

• Users can have multiple proxy addresses beyond their primary SMTP address.
• Emails sent to any of the proxy addresses will get delivered to the user’s mailbox.
• Useful for shared mailboxes, aliases, external domains, DLs, etc.
• Proxy addresses appear as additional emails when looking up the user.
• Set on user accounts in Active Directory then sync to Exchange Online.
• Must follow the standard email address format – “name@domain.com”.

PowerShell provides easy management of proxy addresses at scale across many AD user accounts.

Prerequisites

To follow along with the PowerShell examples, you will need:

• Windows Server with Active Directory Domain Services (AD DS)
• Exchange Server or Exchange Online configured
• Active Directory user accounts already created
• PowerShell 5.1 or higher
• Admin access to manage user accounts in AD

This guide assumes AD and Exchange are already set up and email is working normally.

Retrieving Existing Proxy Addresses

To view the proxy addresses currently set on a user account, use the Get-ADUser cmdlet.

Here’s an example to retrieve addresses for the user jsmith:

# Retrieve the AD user object
$user = Get-ADUser jsmith

# View just the proxyAddresses attribute
$user.ProxyAddresses

This will output any existing proxies like:

smtp:jsmith@company.com
smtp:john.smith@company.com

You can also filter Get-ADUser to return all users that have a specific proxy address:

# Find accounts with this proxy 
Get-ADUser -Filter "ProxyAddresses -like '*@company.com'"

This lets you easily check for a proxy already taken before assigning it to a new user.

Adding a Single Proxy Address

To add a new proxy address to an existing user, use Set-ADUser with the -Add parameter:

Set-ADUser jsmith -Add @{ProxyAddresses="smtp:j.smith@company.com"}

This will append the j.smith@company.com proxy to the user without affecting any existing addresses.

You can likewise remove a single proxy:

Set-ADUser jsmith -Remove @{ProxyAddresses="smtp:john.smith@company.com"} 

Just specify the exact proxy address string to add or remove.

This approach is useful for changing proxies individually but inefficient for bulk updates.

Adding Multiple Proxy Addresses

For bulk proxy address management, the best approach is to build the full array of addresses you want assigned to the user.

Suppose we want to configure these proxies:

• Primary SMTP: jsmith@company.com
• Alias: john.smith@company.com
• Previous domain: jsmith@oldcompany.com

Here is how to build the proxy array:

# Construct array of proxies
$proxies = @(
    "smtp:jsmith@company.com",
    "smtp:john.smith@company.com",
    "smtp:jsmith@oldcompany.com"
)

# Set all proxies at once
Set-ADUser jsmith -Add @{ProxyAddresses=$proxies}

This overrides any existing values and establishes the proxy array exactly as defined.

For another user with different requirements, we easily construct a different set:

# Proxies for different user
$proxies = @(
    "smtp:mjones@company.com", 
    "smtp:marketing@company.com"
)

Set-ADUser mjones -Add @{ProxyAddresses=$proxies}

This approach allows easily managing proxies in bulk by constructing the desired array for each user.

Removing All Proxy Addresses

To fully reset and remove all proxy addresses for a user, set the array to $null:

Set-ADUser jsmith -Add @{ProxyAddresses=$null}

This will clear any previously defined proxies and leave just the primary SMTP address.

As a best practice, do not remove the primary SMTP proxy as it will likely break email functionality.

Modifying Proxy Addresses in a CSV

For managing many AD user accounts and proxies, importing data from a CSV file is useful.

Say we have a CSV like:

Name,PrimaryAddress,Proxy1,Proxy2
John Smith,jsmith@company.com,john.smith@company.com,jsmith@oldcompany.com
Mary Jones,mjones@company.com,m.jones@company.com,mjones@oldcompany.com

We can process this in PowerShell:

# Import CSV module
Import-Module ActiveDirectory

# Import CSV file
$users = Import-Csv -Path proxies.csv

# Loop through each row
foreach ($user in $users) {

  # Construct proxy array from columns    
  $proxies = @(
        "smtp:" + $user.PrimaryAddress
        "smtp:" + $user.Proxy1
        "smtp:" + $user.Proxy2
  )

  # Set proxies on AD user account
  Set-ADUser -Identity $user.Name -Add @{ProxyAddresses=$proxies}

}

This allows managing bulk proxy updates for many AD users using simple CSV data.

The same approach works for removing proxies – just create a CSV with only the primary addresses.

Troubleshooting Common Proxy Scenarios

Here are solutions for some common scenarios and issues that may arise:

Assigning aliases – Set “smtp:alias@company.com” as a proxy on the user’s account.

Shared mailboxes – Make sure the shared address is a proxy on every user needing access.

External/previous domains – Add “smtp:user@olddomain.com” to receive those emails.

Duplicates – Proxies must be unique. Remove any dupes or typos causing issues.

Deliverability problems – If emails to a proxy address don’t work, re-sync to Exchange after adding it.

Invalid format – Proxy must be a valid email like “user@domain.com”. Fix any formatting issues.

Exchange attribute limit – If you exceed the 500 proxy limit, remove unused legacy addresses.

Addressing these common scenarios when managing proxy addresses will help avoid problems.

Automating Proxy Management

Here are some ways to further automate proxy address management:

• Use a GUI – Tools like Active Directory Users & Computers provide a user interface for updating proxies.
• Integrate with HR systems – Automate proxy assignments and changes based on HR employee records.
• Sync from cloud directories – Tools like Azure AD Connect can sync proxy changes from the cloud to AD.
• Manage with scripts – Schedule and run PowerShell scripts to routinely add/update proxies.

Automating parts of the proxy management process can save administrative time and effort.

Best Practices for Proxy Addresses

When working with proxy email addresses, follow these best practices:

• Only assign proxies needed for valid business purposes.
• Keep the primary SMTP address as the user’s main email.
• Watch out for duplicate or invalid proxy formats.
• Remove old, unused proxies to avoid hitting Exchange limits.
• Avoid typos and misspellings that could cause deliverability issues.
• Confirm changes replicate successfully to Exchange Online.
• Automate and schedule regular proxy updates where possible.

Adhering to these best practices will keep your proxy environment clean and minimize administrative overhead.

Summary

Managing proxy email addresses in Active Directory is straightforward using PowerShell:

• Retrieve existing proxy addresses with Get-ADUser
• Add or remove individual proxies with Set-ADUser
• Build proxy address arrays for bulk changes
• Import CSV files to modify many users
• Automate with scripts and HR system integration

Following the examples in this guide will allow you to efficiently manage proxies for AD user mailboxes at scale. Properly assigning proxy addresses enables functionality for aliases, distribution groups, shared mailboxes and more.

Further Reading

For more on proxy address management in Active Directory, refer to these resources:

• Microsoft Docs – ProxyAddresses Attribute
• Microsoft Blog – Managing Proxy Addresses
• Microsoft 365 Admin Center – Manage Proxy Addresses
• PowerShell Gallery – Exchange Online Module
• Microsoft Docs – Set-ADUser examples

Using the techniques in this guide along with Microsoft’s additional documentation will enable you to become proficient in managing Active Directory proxy addresses via PowerShell scripts and automation.