Manage Mail-Enabled Security Groups using PowerShell

Mail-enabled security group is nothing but the security group which also acts as a distribution list. In this post, we will explore how to create a new mail-enabled security group, and manage members and owners of the group using the Exchange Online PowerShell.

A mail-enabled security group can be used to distribute messages as well as to grant access permissions to Azure AD and SharePoint resources. Since this group is being used for dual purposes, the Security part is controlled by Azure AD, and the Message distribution part is controlled by Exchange Online.

Before you start, install the latest Exchange Online Powershell module and run the following command to connect the module.

Connect-ExchangeOnline

Create a new mail-enabled security group

We can use the New-DistributionGroup cmdlet to create a new mail-enabled security group. The below command creates a security group with an email alias “itdepartment” and the name “IT Department”.

New-DistributionGroup -Name "IT Department" -Alias "itdepartment" -Type "Security"

You can also specify group owners and members while creating the group.

$Owners = @('[email protected]','[email protected]')
$Members = @('[email protected]','[email protected]','[email protected]')
New-DistributionGroup -Name "HR Department" -Alias "hrdepartment" -Type "Security" -ManagedBy $Owners -Members $Members

List mail-enabled security groups

Once you successfully created a group, use the Get-DistributionGroup cmdlet to retrieve the group details.

Get-DistributionGroup -Identity "HR Department" | Format-List

Use the following command to get a list of all security groups in the organization.

Get-DistributionGroup -ResultSize Unlimited -Filter "RecipientTypeDetails -eq 'MailUniversalSecurityGroup'"

Add members and owners to a group

We can use the Add-DistributionGroupMember cmdlet to add a member to the mail-enabled security group.

Add-DistributionGroupMember "IT Department" -Member "[email protected]"

There is no separate cmdlet to add owners to a group as like members. The owner details are available in the ManagedBy attribute of the group. So, we can use the Set-DistributionGroup cmdlet to update owners. The below command overwrites all existing entries, removes the existing owners, and updates the new owners.

$Owners = @('[email protected]' , '[email protected]')
Set-DistributionGroup -Identity "IT Department" -ManagedBy $Owners

To add or remove owners without affecting other existing owners, use the following syntax:

$OwnersToAdd = @('[email protected]','[email protected]')
Set-DistributionGroup -Identity "IT Department" -ManagedBy @{Add=$OwnersToAdd;}

$OwnersToRomve = @('[email protected]','[email protected]')
Set-DistributionGroup -Identity "IT Department" -ManagedBy @{Remove=$OwnersToRomve;}

Add bulk members to a group from CSV

Consider the CSV file “GroupMembers.csv” (Download sample CSV) that includes the column header “UserPrincipalName” which holds the user identity values in each row of the CSV file. Run the below script to add members in bulk to a mail-enabled security group by importing users from the given CSV file.

#Specify your mail-enabled security group
$GroupId = "IT Department"
 
#Read group members from CSV file
$CSVRecords = Import-CSV "C:\Temp\GroupMembers.csv"
$TotalMembers = $CSVRecords.Count
$i = 0
 
#Iterate members one by one and add to the group
ForEach($CSVRecord  in $CSVRecords)
{
$User = $CSVRecord."UserPrincipalName"

$i++;
Write-Progress -Activity "Adding member $User" -Status "$i out of $TotalMembers members completed"

Try
{
#Add member to the group
Add-DistributionGroupMember -Identity $GroupId -Member $User -ErrorAction Stop
}
catch
{
Write-Host "Error occurred for $User" -f Yellow
Write-Host $_ -f Red
}
}

Export members and owners to a CSV file

We can use the Get-DistributionGroupMember cmdlet to list members. The below command retrieves the members from a single group.

Get-DistributionGroupMember -Identity "IT Department" -ResultSize Unlimited

Export all groups and their members

The following commands first retrieve all the mail-enabled security groups, iterate each group and get members, and finally export all the groups and their members to a CSV file.

$Result = @() #Result array

#Get all mail-enabled security groups
$MailSecurityGroups = Get-DistributionGroup -ResultSize Unlimited -Filter "RecipientTypeDetails -eq 'MailUniversalSecurityGroup'"

$TotalGroups = $MailSecurityGroups.Count
$i = 0

#Iterate groups one by one and get members
ForEach($Group in $MailSecurityGroups )
{
$i++;
#Get group members and add to the Result array
Write-Progress -Activity "Get members for the group $($Group.DisplayName)" -Status "$i out of $TotalGroups groups completed"
Try
{
#Get members
$GroupMembers = Get-DistributionGroupMember -Identity $Group.Identity -ErrorAction Stop 

#Add members one by one to the Result array
ForEach($Member in $GroupMembers)
{
$Result += New-Object PSObject -property @{ 
GroupName = $Group.DisplayName
Member = $Member.DisplayName
PrimarySmtpAddress = $Member.PrimarySmtpAddress
}
}

}
Catch 
{
Write-Host "Error occurred for the group $($Group.Displayname)" -f Yellow
Write-Host $_ -f Red
}

}
#Display the group members
#$Result | Select GroupName,Member,PrimarySmtpAddress
#Export the result to a CSV file.
$Result | Export-CSV "C:\Temp\Mail-Security-Group-Members.csv" -NoTypeInformation -Encoding UTF8

Export all groups with their owners

We can extract the owner info from the ManagedBy attribute in Get-DistributionGroup cmdlet. The following command exports the groups with owner details.

Get-DistributionGroup -ResultSize Unlimited -Filter "RecipientTypeDetails -eq 'MailUniversalSecurityGroup'" |
Select DisplayName,ManagedBy | Export-CSV "C:\Temp\Mail-Security-Group-Owners.csv" -NoTypeInformation -Encoding UTF8