How to modify email addresses with PowerShell 2.0

One of the most asked question across many PowerShell forums, by Exchange administrators, is how to modify email addresses for mailbox users. The most common used code to add new email address in Exchange 2007 is:

PS > $mbx = Get-Mailbox shay

PS > $mbx.EmailAddresses += “newAddress@domain.com”

PS > Set-Mailbox -Identity $mbx –EmailAddresses $mbx.EmailAddresses

With Windows PowerShell 2.0 and Exchange 2007 (and above, sorry guys no 2003 ) we can use the Update-List cmdlet to add,remove or replace email addresses in a middle of a pipeline.

PS > Get-Mailbox shay | Select-Object -ExpandProperty EmailAddresses | `
     Where-Object {$_.PrefixString -eq 'smtp'}


SmtpAddress        : shay@domain.com
AddressString      : shay@domain.com
ProxyAddressString : SMTP:shay@domain.com
Prefix             : SMTP
IsPrimaryAddress   : True
PrefixString       : SMTP

We see that my mailbox has only one email address. Lets try to add two more addresses and then get the email addresses collection back:

PS > Get-Mailbox shay | `
     Update-List -Property EmailAddresses -Add ScriptFanatic@domain.com,ShayL@domain.com | `
     Set-Mailbox



PS > Get-Mailbox shay | Select-Object -ExpandProperty EmailAddresses | `
     Where-Object {$_.PrefixString -eq 'smtp'} 

SmtpAddress        : ShayL@domain.com
AddressString      : ShayL@domain.com
ProxyAddressString : smtp:ShayL@domain.com
Prefix             : SMTP
IsPrimaryAddress   : False
PrefixString       : smtp

SmtpAddress        : ScriptFanatic@domain.com
AddressString      : ScriptFanatic@domain.com
ProxyAddressString : smtp:ScriptFanatic@domain.com
Prefix             : SMTP
IsPrimaryAddress   : False
PrefixString       : smtp

SmtpAddress        : shay@domain.com
AddressString      : shay@domain.com
ProxyAddressString : SMTP:shay@domain.com
Prefix             : SMTP
IsPrimaryAddress   : True
PrefixString       : SMTP

UPDATE [11/22/2010]: The method described below no longer works in Exchange 2010 and Exchange 2007 SP2. Check this post for more information.

Notice that the primary email address is indicated by the ProxyAddressString property (True) and the ProxyAddressString property which starts the with an uppercased prefix of ‘SMTP:’ . To remove email addresse(s) we use the –Remove parameter:

PS > Get-Mailbox shay | ` 
     Update-List -Property EmailAddresses –Remove ScriptFanatic@domain.com,ShayL@domain.com | ` 
     Set-Mailbox 

The Add and Remove parameters can be used together in a pipeline, however we cannot remove the primary address:

PS > Get-Mailbox shay | `
     Update-List -Property EmailAddresses -Remove shay@domain.com | Set-Mailbox
Update-List : Cannot remove the primary SMTP address 'shay@domain.com'. 
Please promote another valid SMTP address before removing this one.

But we can set a new email address as the primary address (and remove the old one later), just add the ‘SMTP:’ prefix.

PS > Get-Mailbox shay | Update-List -Property EmailAddresses -Add "SMTP:PSFanatic@domain.com" | Set-Mailbox

From the Update-List cmdlet help description:

“This cmdlet works only when the property that is being updated supports the IList interface that Update-List uses. Also, any Set-* cmdlets that accept an update must support the IList interface. The core cmdlets that are installed with Windows PowerShell do not support this interface. To determine whether a cmdlet supports Update-List, see the cmdlet Help topic.”

So, what other properties support the IList interface? With the following command you can get a list of mailbox properties that can be modified with Update-List.

PS > $mbx = Get-Mailbox shay 
PS > $mbx.GetType().GetProperties() | `
     Where-Object {$_.PropertyType.GetInterface("System.Collections.IList",$true)} | `
     Select-Object Name 

Name 
---- 
Languages 
ProtocolSettings 
ResourceCustom 
Extensions 
AcceptMessagesOnlyFrom 
AcceptMessagesOnlyFromDLMembers 
AddressListMembership 
EmailAddresses 
GrantSendOnBehalfTo 
PoliciesIncluded 
PoliciesExcluded 
RejectMessagesFrom 
RejectMessagesFromDLMembers 
UMDtmfMap 
ObjectClass

Finally, there is also a –Replace parameter we can use to replace all existing email addresses with new ones. For more information see the code examples for Update-List.