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
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.
