Using the Alias Parameter with the New-Team Cmdlet

Why New-Team Needs an Alias

Alias, or mailNickname, is a value assigned to mail-enabled Office 365 recipients. The value of the alias must be unique for Office 365 Groups.

When you run New-Team to create a new team, Teams creates a value for the alias for the new team (and its underlying Office 365 group). Teams also generates unique values for the Name and PrimarySMTPAddress properties. For example, here’s what Teams generates for a new team as viewed with the Get-UnifiedGroup cmdlet if you don’t pass a value for the Alias parameter:

Name               : msteams_3e8d41_245f9292-29ca-4773-9240-de5fcee03853
Alias              : msteams_3e8d41
PrimarySmtpAddress : msteams_3e8d41@office365itpros.com

The name given to the team is composed of “msteams,” an underscore, and the Azure Active Directory object identifier for the team. The alias is derived from the name and the SMTP address uses the alias and the default tenant domain. Users only ever see the display name of a team, so having such a value in its name doesn’t make any difference.

Passing the Alias

If you use Teams messaging for communication, you probably aren’t concerned about email, so generating automatic values for these properties might not be an issue, but if you want to control the email address assigned to a new team, include the name you want to use in the Alias parameter. For instance, if I pass “Ignite2019” in the Alias, the following values are used:

New-Team -DisplayName "Ignite 2019 Attendees" -AccessType Public -AddCreatorAsMember $True -Classification Confidential -Description "A team for Ignite 2019 Attendees" -Alias Ignite2019

Name               : Ignite2019_bb966263-a263-4731-8454-afbd7be22b81
Alias              : Ignite2019
PrimarySmtpAddress : Ignite2019@office365itpros.com

Make sure that any alias you pass to New-Team is unique as the cmdlet will fail if you try to use a value that already exists for another object in the tenant.

---

This is information from Chapter 14 of the Office 365 for IT Pros eBook, where we investigate the finer points of managing Office 365 Groups and Teams with PowerShell.