Bulk add secondary SMTP address with PowerShell

In the previous article, you learned how to find a missing SMTP address. Now that you have the information, you like to add a secondary SMTP address to the mailboxes. You can add the secondary SMTP address manually, but automating it with a PowerShell script is faster. In this article, you will learn how to bulk add secondary SMTP address with PowerShell.

Table of contents

Introduction

The Add-SMTP.ps1 PowerShell script works for:

  • Exchange on-premises
  • Exchange Hybrid*
  • Exchange Online

*Change the cmdlets in the script from Get-Mailbox to Get-RemoteMailbox and Set-Mailbox to Set-RemoteMailbox.

Prepare the add SMTP address PowerShell script

Download the Add-SMTP.ps1 script or copy and paste the below code in Notepad. Give it the name Add-SMTP.ps1 and place it in the C:\scripts folder. Create a scripts folder if you don’t have one.

# Output will be added to C:\temp folder. Open the Add-SMTP-Address.log with a text editor. For example, Notepad.
Start-Transcript -Path C:\temp\Add-SMTP-Address.log -Append

# Get all mailboxes
$Mailboxes = Get-Mailbox -ResultSize Unlimited

# Loop through each mailbox
foreach ($Mailbox in $Mailboxes) {

    # Search for specified SMTP address in every mailbox
    $SMTPAddress = $Mailbox.EmailAddresses | Where-Object { $_ -like "*@contoso.com" }
      
    # Do nothing when there is already an SMTP address configured
    If (($SMTPAddress | Measure-Object).Count -eq 0) {
	
        # Change @contoso.com to the domain that you want to add
        $Address = "$($Mailbox.Alias)@contoso.com"

        # Remove the -WhatIf parameter after you tested and are sure to add the secondary email addresses
        Set-Mailbox $Mailbox.DistinguishedName -EmailAddresses @{add = $Address } -WhatIf

        # Write output
        Write-Host "Adding $($Address) to $($Mailbox.Name) Mailbox" -ForegroundColor Green
    }
}

Stop-Transcript
  • Line 11 and 17: Change the @contoso.com value on both places to the domain that you want to add to the mailboxes.

In my example, this is how it looks. It will look for mailboxes with the domain @alitajran.com. If it’s not set, the SMTP address alias@alitajran.com is added to the mailbox.

# Output will be added to C:\temp folder. Open the Add-SMTP-Address.log with a text editor. For example, Notepad.
Start-Transcript -Path C:\temp\Add-SMTP-Address.log -Append

# Get all mailboxes
$Mailboxes = Get-Mailbox -ResultSize Unlimited

# Loop through each mailbox
foreach ($Mailbox in $Mailboxes) {

    # Search for specified SMTP address in every mailbox
    $SMTPAddress = $Mailbox.EmailAddresses | Where-Object { $_ -like "*@alitajran.com"}
      
    # Do nothing when there is already an SMTP address configured
    If (($SMTPAddress | Measure-Object).Count -eq 0) {
	
        # Change @contoso.com to the domain that you want to add
        $Address = "$($Mailbox.Alias)@alitajran.com"

        # Remove the -WhatIf parameter after you tested and are sure to add the secondary email addresses
        Set-Mailbox $Mailbox.DistinguishedName -EmailAddresses @{add = $Address } -WhatIf

        # Write output
        Write-Host "Adding $($Address) to $($Mailbox.Name) Mailbox" -ForegroundColor Green
    }
}

Stop-Transcript

In the next step, you are going to run the script and see it in action.

Bulk add secondary SMTP address PowerShell script

The script works for Exchange on-premises, Exchange Hybrid, and Exchange Online. You must connect with the proper tools before you run the script:

Go to the script path and run the Add-SMTP.ps1 script. The script will go through all the mailboxes in the Exchange Organization. The -WhatIf parameter is added in the script. If you run the script, nothing will happen in the environment. You will get an output showing what will happen.

In my example, the SMTP address @alitajran.com will be added in bulk. After running the script, confirm that these are the SMTP addresses that need to be added.

[PS] C:\> cd C:\scripts
[PS] C:\scripts>.\Add-SMTP.ps1
Transcript started, output file is C:\temp\Add-SMTP-Address.log
What if: Setting mailbox "exoip.local/Users/Administrator".
Adding Administrator@alitajran.com to Administrator Mailbox
What if: Setting mailbox "exoip.local/Company/Users/HR/Amanda Morgan".
Adding amanda.morgan@alitajran.com to Amanda Morgan Mailbox
What if: Setting mailbox "exoip.local/Company/Users/HR/Christopher Payne".
Adding christopher.payne@alitajran.com to Christopher Payne Mailbox
What if: Setting mailbox "exoip.local/Company/Users/ServiceAccounts/Mary Walsh".
Adding mary.walsch@alitajran.com to Mary Walsh Mailbox
What if: Setting mailbox "exoip.local/Company/Users/HR/Dylan Piper".
Adding Dylan.Piper@alitajran.com to Dylan Piper Mailbox
What if: Setting mailbox "exoip.local/Company/Users/ServiceAccounts/Benetiz Anees".
Adding Benetiz.Anees@alitajran.com to Benetiz Anees Mailbox
Transcript stopped, output file is C:\temp\Add-SMTP-Address.log

Remove the -WhatIf parameter from the PowerShell script and rerun the script. The SMTP addresses are added in bulk.

[PS] C:\scripts>.\Add-SMTP.ps1
Transcript started, output file is C:\temp\Add-SMTP-Address.log
Adding Administrator@alitajran.com to Administrator Mailbox
Adding amanda.morgan@alitajran.com to Amanda Morgan Mailbox
Adding christopher.payne@alitajran.com to Christopher Payne Mailbox
Adding mary.walsch@alitajran.com to Mary Walsh Mailbox
Adding Dylan.Piper@alitajran.com to Dylan Piper Mailbox
Adding Benetiz.Anees@alitajran.com to Benetiz Anees Mailbox
Transcript stopped, output file is C:\temp\Add-SMTP-Address.log

I hope that this helped you to bulk add SMTP addresses to the mailboxes in the Exchange organization.

Read more: List users not inheriting email address policy »

Conclusion

In this article, you learned how to bulk add secondary SMTP address with PowerShell. Download the Add-SMTP PowerShell script. Add the domain that you like to add and run the script. The script output will show which proxy addresses are added. Don’t forget to test first with the -WhatIf parameter, as shown in the article.

Did you enjoy this article? You may also like Get Mailbox size of all users in Exchange with PowerShell. Don’t forget to follow us and share this article.

ALI TAJRAN

ALI TAJRAN

ALI TAJRAN is a passionate IT Architect, IT Consultant, and Microsoft Certified Trainer. He started Information Technology at a very young age, and his goal is to teach and inspire others. Read more »

X TwitterLinkedIn

What Others Are Reading

This Post Has 28 Comments

  1. Hello Ali Tajran,

    I’m currently trying to add a smtp proxyaddress to users in a hybrid environment.
    This smtp address has to be added and set as primary address.
    How do I do that in a bulk?

    Reply

    1. Get the OU distinguishedName and follow the below steps:

      Change lines 4-5 in the script:

      # Get all mailboxes
$Mailboxes = Get-Mailbox -ResultSize Unlimited

      With the below lines:

      # Fill in OU
$OUScope = "OU=IT,OU=Users,OU=Company,DC=exoip,DC=local"

# Get all mailboxes in OU
$Mailboxes = Get-Mailbox -OrganizationalUnit $OUScope -ResultSize Unlimited
      Reply

  3. Hi Ali,

    Thanks for posting this script – saved me having to tediously go thru each mailbox and add a new domain alias. To make the script more platform agnostic I changed the logfile/tmpfolder part (line 2) to:

    $TempFolder=[System.IO.Path]::GetTempPath()
    $LogFile= Join-Path $TempFolder “Add-SMTP-Address.log”
    Start-Transcript -Path $LogFile -Append

    That way I could run it in Linux pwsh 😉

    Thanks,
    Allan

    Reply

  4. Hi Ali,

    Thanks for this article and script. I have tested this using the -WhatIf parameter and it seems to work well, but I was wondering whether it’s possible to apply this script to *UserMailboxes* only, and not *SharedMailboxes* ?

    Thanks!

    Reply

    1. Hi Shawn,

      You can change line 5 to:

      Get-Mailbox -RecipientTypeDetails UserMailbox -ResultSize Unlimited

      The RecipientTypeDetails parameter filters the results by the specified mailbox subtype. Valid values are:

      – DiscoveryMailbox
      – EquipmentMailbox
      – GroupMailbox (Exchange 2013 or later and cloud)
      – LegacyMailbox
      – LinkedMailbox
      – LinkedRoomMailbox (Exchange 2013 or later and cloud)
      – RoomMailbox
      – SchedulingMailbox (Exchange 2016 or later and cloud)
      – SharedMailbox
      – TeamMailbox (Exchange 2013 or later and cloud)
      – UserMailbox

      Reply

      1. Wonderful post and expansion on recipient types! You’ve been a go-to in referencing scenarios and the scripting methodology.

        Reply

  5. *Promps for this article*

    I will expose my scenario here:

    My company will change the site domain and office 365 email domain too. Its an Rebranding.

    So, i came here to find a way to “mass edit” all users to add the new domain, and change the atual domain (SMTP) to smtp aliases. I think this is the way to change the domain and continue receive emails in the old domain, correctly?
    In this case, this script only add the smtp what i type, but do not do all I need, or iam wrong?

    Old : SMTP:user1@contoso.com
    New: SMTP:user1@newdomain.com, smtp:user1@contoso.com

    Reply

  6. Hi Ali,
    Lets say, I need to add secondary address (i.e. proxyaddress) with @newdomain.com for missing set of users. Couple of users already have it and I need to perform below task for Hybrid environment (which ADobjects are syncing with Cloud):

    1. Check if secondary address (i.e. proxyaddress) is missing for any user. The format of secondary address will be Firstname.lastname@newdomain.com (which is Givenname.surname@newdomain.com) for AD objects.
    2. Add secondary address (i.e. Givenname.surname@newdomain.com) to missing user if its already not in use by any other user or ADobject. If its already in use then add keyword as 1 in secondary address and then stamp it. There are high chances that we may have users with same name and One may have secondary address already added and other one doesn’t have it.

    I have tried a lot with Array and If-else function and checked different articles with no success till now. Can someone help for fulfilling the requirement.

    Reply

  7. Best solution I’ve seen to this! Well done.

    I would also love to see something that lets us swap the alias and the primary in bulk :). Going to try and follow similar logic…will post back if I get it.

    Reply

  8. Hi Ali

    I have been requested to add new aliases for the entire company accounts.

    The default email address first.last@company.com.au
    the new Aliases is First.last@newdomain.com.au

    The new domain name added in Azure Admin center and now is showing in the drop list of aliases address.

    I am after getting a script adding new aliases for entire company accounts without effecting the default email address. is that script works in my case?

    Thanks in advance.

    Reply

  11. Hi,

    This was by far the best script i have seen for this purpose. Do you have a similar script that can be used to enable email forwarding for all users where the forwarding address will be “alias”@domain.com?

    Thank you!

    Reply

    2. Did you ever figure this out or get it to work? I am trying to do the same thing but having trouble finding the right script to do it. Thanks Scott.

      Reply

  13. Hi Ali,

    Is there a way to incorporate this to an environment where Azure AD Connect Sync is in play. I recently discovered a new email domain that I need to add as a secondary alias for users that are Azure AD synced.

    Reply

  14. Hello Ali,

    I have a situation where i need to a email address and make it primary as well, can you please help me.
    I tried to modify your above script but getting below errors.
    Cannot process argument transformation on parameter ‘EmailAddresses’. Cannot convert value
    “System.Collections.Hashtable” to type “Microsoft.Exchange.Data.SmtpAddress”. Error: “Cannot convert hashtable to an
    object of the following type: Microsoft.Exchange.Data.SmtpAddress. Hashtable-to-Object conversion is not supported in
    restricted language mode or a Data section.”
    + CategoryInfo : InvalidData: (:) [Set-Mailbox], ParameterBindin…mationException
    + FullyQualifiedErrorId : ParameterArgumentTransformationError,Set-Mailbox
    + PSComputerName :

    Reply

  16. Hi, and great article.
    Can you specify to only add a secondary SMTP to room mailboxes? Just add “-recipienttypedetails roommailbox” on line 5?

    Thanks

    Reply

    1. Hi Joachim,

      Glad that you like the article.

      If you only want to target room mailboxes, change it to the following:

      From:
      $Mailboxes = Get-Mailbox -ResultSize Unlimited

      To:
      $Mailboxes = Get-Mailbox -RecipientTypeDetails RoomMailbox -ResultSize Unlimited

      Reply

  17. Hello Ali,
    Nice article. I was just wondering if you ever had to do this where you need add more than one secondary SMTP address and for example make one of the primary SMTP ? Thank you in advance.
    Best regards,
    Karol

    Reply

  18. Hey there Ali,

    I was trying to use the script but get the following error:

    Adding USERNAME@domain.com to USERNAME Mailbox
    Cannot process argument transformation on parameter ‘Identity’. Cannot convert value “USERNAME” to type
    “Microsoft.Exchange.Configuration.Tasks.MailboxIdParameter”. Error: “Cannot convert the “USERNAME” value of type
    “Deserialized.Microsoft.Exchange.Data.Directory.Management.Mailbox” to type
    “Microsoft.Exchange.Configuration.Tasks.MailboxIdParameter”.”
    + CategoryInfo : InvalidData: (:) [Set-Mailbox], ParameterBindin…mationException
    + FullyQualifiedErrorId : ParameterArgumentTransformationError,Set-Mailbox
    + PSComputerName : outlook.office365.com
    Cannot process argument transformation on parameter ‘Identity’. Cannot convert value “USERNAME” to type
    “Microsoft.Exchange.Configuration.Tasks.MailboxIdParameter”. Error: “Cannot convert the “USERNAME” value of type
    “Deserialized.Microsoft.Exchange.Data.Directory.Management.Mailbox” to type
    “Microsoft.Exchange.Configuration.Tasks.MailboxIdParameter”.”
    + CategoryInfo : InvalidData: (:) [Set-Mailbox], ParameterBindin…mationException
    + FullyQualifiedErrorId : ParameterArgumentTransformationError,Set-Mailbox
    + PSComputerName : outlook.office365.com

    Any tips on what could be going wrong?

    Cheers,
    Henk

    Reply

    1. Hi Henk,

      I redacted sensitive information from your comment.

      You are running the script against the Microsoft 365/Office 365 tenant, which is why you are getting this error.

      The Add-SMTP.ps1 PowerShell script was intended to work only for Exchange on-premises and Exchange Hybrid environments. I updated the script and the article with extra information.

      It works now for Exchange on-premises, Exchange Hybrid, and Exchange Online (Microsoft 365/Office 365).

      Reply

Leave a Reply

Your email address will not be published. Required fields are marked *