Skip to content

Manage Distribution Group using PowerShell in Office 365 | Creating and managing Distribution Groups | Part 2#5

The current article is that second article on the five-article series, which is dedicated to the subject of managing Distribution Group in Office 365 and Exchange Online based environment using PowerShell.The article includes two main sections:

  1. Creating New Distribution Group.
  2. Configure the setting of existing Distribution Group.

Manage Distribution Group using PowerShell in Office 365 | Article Series

Updating Distribution Group and the error – You don’t have sufficient permissions

Each Distribution Group has at least one “owner.”

Technically speaking, only the Distribution Group owner is “allowed” to perform management tasks such as updated to the Distribution Group.

In case that Exchange Online Administrator tries to update properties of Distribution Group, which he is not the owner of this Distribution Group, in some scenarios, the following error message appears:

Error: You don’t have sufficient permissions. This operation can only be performed by a manager of the group.

Notice that although the user performing an update of the Distribution Group properties has Global Administrator credentials, the fact that he is not the Distribution Group owner could stop him from complete the required management task.

The good news is that the PowerShell cmdlets that we use for managing Distribution Group include a parameter named BypassSecurityGroupManagerCheck.

In case that you try to perform a management task, and the “permission error” appears, you can add the BypassSecurityGroupManagerCheck parameter to the original PowerShell command.

PowerShell command syntax example:

Set-DistributionGroup -Identity "<Distribution Group Name>" –ManagedBy <Identity> -BypassSecurityGroupManagerCheck

1. Creating New Distribution Group

When we use PowerShell for creating a NEW Distribution Group without any parameters besides of the Distribution Group name, the Distribution Group will be created with the following default options:

  • E-mail address – the default E-mail address that will be created for the NEW Distribution Group will include the tenant onmicrosft.com domain name.
  • Delivery management – the default option that will be set is – “Only senders inside my organization.” The meaning is that the external recipient will not be allowed to send E-mail to the Distribution Group.
  • Ownership = The Distribution Group ownership will be assigned automatically to the user account that creates the Distribution Group.

One option is to use PowerShell for creating a NEW Distribution Group, and in the second, phase set all the required settings.

The other option is to use a PowerShell command with additional parameters, that will create the NEW Distribution Group + set additional setting’s options.

Create NEW Distribution Group (use default settings)

PowerShell command syntax:

New-DistributionGroup -Name "<Distribution Group Name>"

PowerShell command example:

New-DistributionGroup -Name “Sales USA”

Create NEW Distribution Group + set additional Distribution Group settings

In case that we want to avoid from the default settings of a NEW Distribution Group when we create the Distribution Group by using PowerShell, we can “extend” that information that we provide to the PowerShell command, so we will be able to better control results.

In the following table, we can see an example to a parameter that we can use when running a PowerShell command for creating a NEW Distribution Group:

PowerShell ParameterDescription
AliasIn case that we don’t provide an Alias name for the NEW Distribution Group, the Alias name will be automatically generated using the Distribution Group name but without spaces.
NameThis is a mandatory value. The Name parameter specifies the unique name of the group. The maximum length is 64 characters. If the value contains spaces, enclose the value in quotation marks (“).
Display nameIn case that we don’t provide the Display name, the display name default value is the “text” that appears in the parameter “name.”
PrimarySmtpAddressWhen creating, a new Distribution Group the only option that relates to E-mail address identity to set the Distribution Group primary E-mail address. (When using the PowerShell cmdlets Set-DistributionGroup.
We can also use the parameter EmailAddresses for creating Alias E-mail address.
ManagedByThe ManagedBy parameter, specifies an owner for the group. A group must have at least one owner. If you don’t use this parameter to specify the owner when you create the group, the user account that created the group is the owner.

Create NEW Distribution Group + set additional Distribution Group settings

PowerShell command syntax:

New-DistributionGroup -Name <Distribution Group name> -DisplayName <DL display name> 
-Alias <Alias>-PrimarySmtpAddress <Email Address> -ManagedBy <identity>

PowerShell command example:

New-DistributionGroup -Name “Sales USA” -DisplayName “Sales USA mail list” -Alias “SalesUSA”
-PrimarySmtpAddress SalesUSA@o365info.com -ManagedBy Brad

Create NEW Security Distribution Group

In case that we want to create a Distribution Group but in addition, define the NEW Distribution Group as a “security group” (a group which can be assigned with permissions), we can use the PowerShell parameter “Type Security.”

In this case, the NEW group will have all the “properties” of Distribution Group and in addition, will also we considered as a “Security Group.”

Create NEW Security Distribution Group

PowerShell command syntax:

New-DistributionGroup -Name <Distribution Group Name> -Type Security

PowerShell command example:

New-DistributionGroup -Name “Sales Italy” -Type Security

Creating Distribution Groups by importing information from a CSV File

The main use of such a requirement is a scenario in which the organization has an existing mail information or other organization application that includes already information about existing Distribution Groups.

In this case, we would like to avoid the need of creating manually a large amount of Distribution Group using the Exchange Online admin center.

Instead, we wish to “bulk creates” the Distribution Groups by importing the information from a CSV file.

Besides of importing the information about the Distribution Group name, we can add to the CSV file additional parameters such as the “type” of the Distribution Group (standard Distribution Group or a security Distribution Group).

Creating Distribution Groups by importing information from a CSV File

PowerShell command syntax:

Import-CSV <Path> | ForEach {New-DistributionGroup -Name $_.name -Type $_.Type}

PowerShell command example:

Import-CSV C:\Temp\DL-Group.csv | ForEach {New-DistributionGroup -Name $_.name -Type $_.Type}
Creating Distribution Groups by importing information from a CSV File

2. Manage existing Distribution Group settings

Enable or disable Distribution Group to get E-mail from external senders

By default, the Exchange Online Distribution Group is configured not to accept email messages from recipients, which are not organization recipients (external senders).

In case that we want to enable an external recipient to send E-mail to the Exchange Online Distribution Group, we can use the PowerShell parameter – RequireSenderAuthenticationEnabled.

By default, the Distribution Group value RequireSenderAuthenticationEnabled is equal to “$True”.

The meaning is that non-authenticated recipient (anonymous recipient or non-organization recipients), will get an NDR (Non-Delivery Report) message when they try to send an E-mail to the Office 365 Distribution Group.

Enable or disable Distribution Group to get E-mail from external senders

To enable the external recipient to send E-mail to Exchange Online Distribution Group, we set the value of the parameter “RequireSenderAuthenticationEnabled” to $False.

PowerShell command syntax:

Set-DistributionGroup "<Distribution Group Name>" -RequireSenderAuthenticationEnabled $False

Powershell command example:

Set-DistributionGroup “Sales USA” -RequireSenderAuthenticationEnabled $False

Enable an external recipient to send E-mail to all Distribution Groups (bulk mode)

In case that we want to change the default setting of the delivery management to every Distribution Group at once (bulk mode) we can use the following PowerShell command:

Enable an external recipient to send E-mail to all Distribution Groups (bulk mode)

PowerShell command example:

Get-DistributionGroup | Set-DistributionGroup -RequireSenderAuthenticationEnabled $False

Adding or replacing Distribution Group owner

In the following section, we review a couple of scenarios that relate to the subject of managing the Distribution Group owner.

The ManagedBy parameter specifies an owner for the group. A group must have at least one owner. If you don’t use this parameter to specify the owner when you create the group, the user account that created the group is the owner. The group owner can:

  • Modify the properties of the group
  • Add or remove group members
  • Delete the group
  • Approve a member depart or join requests (if available)
  • Approve messages sent to the group if moderation is enabled, but no moderators are specified.

By default, the person who creates a group is the owner. All groups must have at least one owner, and Distribution Group can have multiple owners.

Note – in some scenarios in case that the Distribution Group has an existing owner, we will get an error message when we try to update the existing owner information that informs us that we cannot make the required change because we are not the owner of the Distribution Group.
To be able to “bypass” this limitation, we can add to the PowerShell command the parameter – BypassSecurityGroupManagerCheck.

Scenario 1 – Replace existing Distribution Group owner

In this scenario, the Distribution Group already have an owner, and we wish to replace the current Distribution Group owner by assigning a NEW Distribution Group owner\s.

The PowerShell command that we use is:

Replace existing Distribution Group owner

Powershell command syntax:

Set-DistributionGroup -Identity "<Distribution Group Name>" –ManagedBy <Identity>

Powershell command example:

Set-DistributionGroup -Identity "Sales USA" -ManagedBy Brad -BypassSecurityGroupManagerCheck

Scenario 2 – Adding additional owner\s to Distribution Group

In the current scenario, we would like to “keep” existing Distribution Group owner and add additional Distribution Group owners (vs. the previous scenario in which we “remove” existing Distribution Group owner and replace this owner by providing the name of a NEW Distribution Group owner).

To be able to fulfill this requirement, we will not use the “standard” PowerShell syntax and instead, we use the following PowerShell syntax to add or remove one or more values without affecting any existing entries: @{Add=””,””…; Remove=””,””…}.

Adding additional owner\s to Distribution Group

PowerShell command syntax:

Set-DistributionGroup “<Distribution Group name>” -ManagedBy 
@{Add='<Identity 1>','<Identity 2>'}

PowerShell command example:

Set-DistributionGroup “Sales USA” -ManagedBy @{Add='bob','brad'}

Scenario 3 – Adding additional owner\s to Distribution Group + removing existing Distribution Group owners

In the current scenario, we have Distribution Group that has a couple of owners.

We wish to implement the following requirements:

  • Add NEW Distribution Group owners.
  • Remove some of the existing Distribution Group owners.

To be able to fulfil this requirement, we use the following PowerShell command syntax:

Adding additional owner\s to Distribution Group + removing existing Distribution Group owners

PowerShell command syntax:

Set-DistributionGroup “<Distribution Group name>” -ManagedBy @{Add='<Identity 1>','<Identity 2>'; Remove='<Identity 1>' }

PowerShell command example:

Set-DistributionGroup “Sales USA” -ManagedBy @{Add='bob','bradp' ; Remove='Angelina' }

Scenario 4 – Replace existing Distribution Group owner and import “NEW Distribution Group owner” from a CSV file

In this scenario, the information about the Distribution Group + the users who will be configured as the Distribution Group owner is stored in a CSV file.

In the following screenshot, we can see the content of the CSV file that we use.
The CSV file includes two columns:

  • GroupName – this is the column header that stores the information about the Distribution Groups.
  • ManagedBy – this is the column header that stores the information about the user name that we wish to define as the Distribution Group owner.
Replace existing Distribution Group owner and import NEW Distribution Group owner from a CSV file

In our example, the CSV file name is Distribution-Groups-information.csv

Replace existing Distribution Group owner and import “NEW Distribution Group owner” from a CSV file

PowerShell command example:

$GroupList = Import-CSV C:\temp\Distribution-Groups-information.csv
ForEach ($group in $GroupList)
{
ForEach ($user in $GroupList)
{
}
Set-DistributionGroup -BypassSecurityGroupManagerCheck -Identity $group.GroupName -managedby $user.ManagedBy
}

Scenario 5 – Assign Distribution Group owner (replacing the existing Distribution Group owner) for all existing Distribution Groups (Bulk mode)

In the current scenario, we wish to define a specific user as the owner of all existing Distribution Groups. Notice that in this case, we want to remove (replace) the existing Distribution Group owner and assign a NEW owner of the Distribution Group.

Note – in case you need to add the username as the additional Distribution Group owner instead of replacing the existing Distribution Group owner, use the PowerShell syntax that appears in the previous section.

The first part of the PowerShell command gets a list of every existing Distribution Group.

The second part of the PowerShell command will add the specific user as an owner to the list of the Distribution Group that we got from the first part.

In case that we want to add a specific owner to all existing Distribution Groups, we can use the following PowerShell syntax:

Assign Distribution Group owner (replacing the existing Distribution Group owner) for all existing Distribution Groups (Bulk mode)

PowerShell command syntax:

Get-DistributionGroup |Set-DistributionGroup -ManagedBy <Identity> 
–BypassSecurityGroupManagerCheck

PowerShell command example:

Get-DistributionGroup | Set-DistributionGroup -ManagedBy Brad –BypassSecurityGroupManagerCheck

Scenario 6 – Assigning Distribution Group owner (replacing the existing Distribution Group owner) for all Distribution Groups that was created in the last two weeks (Bulk mode)

In the following example, we want to add the user Brad as a Distribution Group owner for all the Distribution Group that was created in the last 2 weeks.

  • Part 1#2 – in the first part of the PowerShell command, we define the PowerShell variable named – $AllNewDistributionGroups, that will store the output of a PowerShell query that “fetch” all the Distribution Group that their “creation time value” is a date that included in the “two weeks range” that we define.
  • Part 2#2 – In the second part of the PowerShell command, we use the “ForEach” PowerShell statement, for executing a “loop process” on the results (add Bob to each of the Distribution Group that appear on the list as an Owner).

The PowerShell “time unit” that we use

PowerShell doesn’t include a parameter that defines “week” as a “Time unit.” To be able to define two-week time range, we define a time range of 14 days.

Assigning Distribution Group owner (replacing the existing Distribution Group owner) for all Distribution Groups that was created in the last two weeks

PowerShell command example:

$AllNewDistributionGroups = Get-DistributionGroup | Where {$_.WhenCreated –ge ((Get-Date).Adddays(-14))}
ForEach ($Group in $AllNewDistributionGroups)
{
Set-DistributionGroup -Identity $Group.name –ManagedBy Bob
}

Manage Distribution Group E-mail address

Each Distribution Group must have a primary email address and may have an additional E-mail address that described as “Alias E-mail address” or “Proxy E-mail addresses.”

The management of Distribution Group E-mail address, can be implemented by using one of the following methods:

  1. Add additional E-mail address to existing Distribution Group E-mail address.
  2. Add additional E-mail address that will “replace” (delete) existing Distribution Group
  3. E-mail address.
  4. Removing an existing E-mail address

Set Distribution Group Primary E-mail address

To replace existing Distribution Group primary E-mail address (defined by the PowerShell
parameter –PrimarySmtpAddress), we can use one of the following PowerShell command options:

Set Distribution Group Primary E-mail address

PowerShell command syntax:

Set-DistributionGroup "<Distribution Group name>" -PrimarySmtpAddress <primary E-mail address>

PowerShell command example:

Set-DistributionGroup "Sales UK" -PrimarySmtpAddress SalesUK@o365info.com

Another variation

PowerShell command syntax:

Set-DistributionGroup "<Distribution Group name>" SMTP:<primary E-mail address>

PowerShell command example:

Set-DistributionGroup "Sales UK" -emailaddresses SMTP:SalesUK@o365info.com

Set Distribution Group Primary E-mail address by importing information from a CSV file

In this scenario, the information about the Distribution Groups + the E-mail addresses that should be assigned as primary E-mail address is stored in a CSV file.

In the following screenshot, we can see the content of the CSV file that we use.
The CSV file includes two columns:

  1. GroupName – this is the column header that stores the information about the Distribution Groups.
  2. email – this is the column header that stores the information about the user name that we wish to define as the Distribution Group owner.
Set Distribution Group Primary E-mail address by importing information from CSV file

In our example, the CSV file name is Distribution-Groups-information.csv

Set Distribution Group Primary E-mail address by importing information from a CSV file

PowerShell command example:

$GroupList = Import-CSV C:\temp\Distribution-Groups-information.csv
ForEach ($group in $GroupList)
{
ForEach ($email in $GroupList)
{
}
Set-DistributionGroup -BypassSecurityGroupManagerCheck -Identity $group.GroupName -PrimarySmtpAddress $email.email
}

Manage Distribution Group Alias E-mail address

The term “Alias E-mail addresses” describe an additional E-mail address beside of the Primary E-mail address.

The process of adding an Alias E-mail address to existing Distribution Group can be implemented in one of the following ways:

  1. Replacing existing Alias E-mail addresses
  2. Adding an additional Alias E-mail address to existing Distribution Group E-mail addresses

To manage Distribution Group E-mail addresses, we use the PowerShell cmdlets-
Set-DistributionGroup + the PowerShell parameter emailaddresses.

Example 1 – Add additional E-mail address to existing Distribution Group E-mail address

In this scenario, we wish to keep existing Distribution Group Alias E-mail addresses and in addition, add additional Alias E-mail addresses.

The PowerShell parameter that we use for adding the additional E-mail addresses is – “@{Add”.

In the following example, the Distribution Group “Sales UK” includes existing Alias E-mail addresses, and we add additional Alias E-mail addresses:

Add additional E-mail address to existing Distribution Group E-mail address

PowerShell command example:

Set-DistributionGroup “Sales UK” -emailaddresses @{Add='
SalesUK02@o365info.com','SalesUK02@o365info.com','SalesUK02@o365info.com'}

Example 2- Replace (remove) existing Distribution Group Alias E-mail addresses and add a NEW E-mail address to Distribution Group

In this scenario, we wish to remove existing E-mail addresses and “replace” the existing E-mail address with a “NEW set” of E-mail addresses.

The “catch” with the following suggested PowerShell command was that the result will be

“Replacement“ of the primary E-mail address + Replacement of existing Distribution Group
Alias E-mail addresses.

The first E-mail address that we provide will replace the existing Distribution Group Primary E-mail address, the rest of the E-mail addresses will replace existing Distribution Group Alias E-mail addresses.

Replace (remove) existing Distribution Group Alias E-mail

PowerShell command example:

Set-DistributionGroup “Sales UK” -emailaddresses 'SalesUK02@o365info.com', 'SalesUK03@o365info.com'

Because of the problematic behavior of the PowerShell command, I suggest that you try to avoid the use of the specified PowerShell syntax.

Example 3- Replace Distribution Group existing E-mail address – Primary + Alias E-mail address

In the following example, we replace existing Distribution Group E-mail addresses by replacing the current Distribution Group Primary E-mail address + replacing the existing Alias E-mail address.

To “declare” a specific E-mail address as a “Primary E-mail address” we use the prefix SMTP with a capital letter. All the rest of the E-mail addresses will be created as Alias E-mail addresses.

Replace Distribution Group existing E-mail address – Primary + Alias E-mail address

PowerShell command syntax:

Set-DistributionGroup "<Distribution Group Name>" -EmailAddresses SMTP:<Primary Email>,<Alias Email>

PowerShell command example:

Set-DistributionGroup "Sales UK" –EmailAddresses SMTP:DL-USA@o365info.com,dev@o365info.com

Example 4- Remove existing Distribution Group Alias E-mail addresses

In the following example, we wish to remove Distribution Group Alias E-mail address \ addresses.

To implement the required removal, we use the PowerShell parameter “@{Remove”.

Remove existing Distribution Group Alias E-mail addresses

PowerShell command syntax:

Set-DistributionGroup “<Distribution Group name>” -EmailAddresses @{Remove='<Identity 1>', '<Identity 2>' }

PowerShell command example:

Set-DistributionGroup "Sales UK" -EmailAddresses @{Remove=' Sales01@o365info.com', ' Sales02@o365info.com' }

Hide Distribution Group from GAL (Global address list)

By default, every Distribution Group appears automatically in the GAL.

In some scenarios, we wish to hide existing Distribution Group by removing the information about the existing Distribution Group from the GAL (Global address list).

To hide existing Exchange Online recipient from the GAL, we use the PowerShell parameter – HiddenFromAddressListsEnabled and set the value to – $True.

Hide Distribution Group from GAL (Global address list)

PowerShell command syntax:

Set-DistributionGroup "<Distribution Group Name>" -HiddenFromAddressListsEnabled $True

PowerShell command example:

Set-DistributionGroup "Sales UK" -HiddenFromAddressListsEnabled $True

Set an existing Distribution Group to accept E-mail only from a specific sender

By default, every organization recipient can send E-mail to Distribution Group.

In case that we want to restrict the ability of an organization recipient to send E-mail to a specific Distribution Group, and define that only specific organization recipient will be allowed to send E-mail to the Distribution Group, we can use the PowerShell parameter –AcceptMessagesOnlyFrom to define the “allowed recipient list.”

Set an existing Distribution Group to accept E-mail only from a specific sender

PowerShell command syntax:

Set-DistributionGroup "<Distribution Group Name>" –AcceptMessagesOnlyFrom <Allowed E-mail address 1>, < Allowed E-mail address 2>

PowerShell command example:

Set-DistributionGroup "Sales UK" –AcceptMessagesOnlyFrom Bradp@o365info.com,Angelina@o365info.com

Define a Distribution Group Moderator

Distribution Group moderator

By default, when we send an E-mail to a Distribution Group, the E-mail is sent automatically to each of the Distribution Group members.

In some scenario, we need to implement a different mail flow, in which E-mail message that is sent to a Distribution Group, will be “accepted” by a specific recipient\s.

The recipient\s which will get the mail need to decide if they approve or decline the
specific E-mail message.

The “person” that we can allocate for this role defined as “Distribution Group Moderator.”

The term “Distribution Group Moderator,” define an entity that needs to approve messages sent to the recipient (Distribution Group members) before the messages are delivered. A moderator must be a mailbox, mail user, or mail contact in your organization.

To PowerShell parameter that we use for defining a “Distribution Group Moderator” is – ModeratedBy.

Define a Distribution Group Moderator

PowerShell command syntax:

Set-DistributionGroup "<Distribution Group Name>" –ModeratedBy <E-mail address>, <E-mail address>

PowerShell command example:

Set-DistributionGroup "Sales UK" –ModeratedBy Bradp@o365info.com,Angelina@o365info.com

Send out of office reply for a Distribution Group

Let’s start with a declaration – The title is a little misleading.

Technically speaking, a Distribution Group object is not an “Exchange mailbox object,” and for this reason, we cannot configure OOO (Out Of Office reply) for existing Distribution Group.

The little trick that we can use, that will partially answer the requirement of defining OOO reply to Distribution Group, is implemented by activating a special Distribution Group parameter named – SendOofMessageToOriginatorEnabled and set the value to $True.

(By default, the value – SendOofMessageToOriginatorEnabled is set to “$False”).

When we “activate” this option, in case that one of the Distribution Group members configures an OOF reply, when a “sender” sends an E-mail message to the Distribution Group, the Distribution Group will “reply” with the OOF messages of the Distribution Group member.

The SendOofMessageToOriginatorEnabled parameter specifies how to handle out of office (OOF) messages for members of the group.

Valid values are:

  • $True When messages are sent to the group, OOF messages for any of the group members are sent to the message sender. This is the default value.
  • $False When messages are sent to the group, OOF messages for any of the group members aren’t sent to the message sender.

Send out of office reply for a Distribution Group

PowerShell command syntax:

Set-DistributionGroup "<Distribution Group Name>" –SendOofMessageToOriginatorEnabled $True

PowerShell command example:

Set-DistributionGroup "Sales UK" –SendOofMessageToOriginatorEnabled $True

Assign “Send As” Permissions to Distribution Group

Assigning Send as permissions to a recipient “on” a Distribution Group, enable the recipient to send E-mail by “hiding” his real identity, and using the identity of the Distribution Group (using the E-mail address of the Distribution Group).

Assign Send As Permissions to Distribution Group

To be able to grant this permission, we can use the following PowerShell command:

Assign “Send As” Permissions to Distribution Group

PowerShell command syntax:

Add-RecipientPermission "<Distribution Group Name>" -Trustee <Identity> -AccessRights SendAs -Confirm:$False

PowerShell command example:

Add-RecipientPermission "Sales UK" -Trustee Brad -AccessRights SendAs -Confirm:$False

Note – we add the PowerShell parameter “Confirm:$False” to avoid the need of conforming the “adding” of the Send As permissions.

The next article in the current article series

o365info Team

o365info Team

This article was written by our team of experienced IT architects, consultants, and engineers.

This Post Has One Comment

  1. I have tried Scenario 4 yet when I run it it seems to only add the last user in the list as the Owner of all the distribution group or maybe it is looping in some way in which it rights the correct one first and then it is rewritten by the last one on the list

Leave a Reply

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