New-DistributionGroup
Applies to: Exchange Server 2013
Important: |
|---|
This topic no longer applies to the cloud-based service. It applies only to on-premises Exchange 2013. To see the current version of the topic that applies to the cloud-based service, change the (v=exchg.150) value in the URL to (v=exchg.160).
|
Use the New-DistributionGroup cmdlet to create distribution groups.
For information about the parameter sets in the Syntax section below, see Syntax.
Note: |
|---|
If you run New-DistributionGroup without specifying an OU, the default OU scope will be wherever the distribution group is being created. Use the OrganizationUnit parameter to specify a different OU.
|
New-DistributionGroup -Name <String> [-Alias <String>] [-ArbitrationMailbox <MailboxIdParameter>] [-BypassNestedModerationEnabled <$true | $false>] [-Confirm [<SwitchParameter>]] [-CopyOwnerToMember <SwitchParameter>] [-DisplayName <String>] [-DomainController <Fqdn>] [-ExternalDirectoryObjectId <String>] [-IgnoreNamingPolicy <SwitchParameter>] [-ManagedBy <MultiValuedProperty>] [-MemberDepartRestriction <Closed | Open | ApprovalRequired>] [-MemberJoinRestriction <Closed | Open | ApprovalRequired>] [-Members <MultiValuedProperty>] [-ModeratedBy <MultiValuedProperty>] [-ModerationEnabled <$true | $false>] [-Notes <String>] [-Organization <OrganizationIdParameter>] [-OrganizationalUnit <OrganizationalUnitIdParameter>] [-OverrideRecipientQuotas <SwitchParameter>] [-PrimarySmtpAddress <SmtpAddress>] [-RoomList <SwitchParameter>] [-SamAccountName <String>] [-SendModerationNotifications <Never | Internal | Always>] [-Type <Distribution | Security>] [-WhatIf [<SwitchParameter>]]
This example creates a mail-enabled universal security group that has the following parameters:
-
The group name is Managers.
-
The group is created in the Users container in the domain contoso.com.
-
The group SamAccountName parameter value is Managers.
-
The group type is Security.
New-DistributionGroup -Name "Managers" -OrganizationalUnit "contoso.com/Users" -SamAccountName "Managers" -Type "Security"
This example creates the distribution group ITDepartment and ignores the naming policy.
New-DistributionGroup -Name "ITDepartment" -IgnoreNamingPolicy
You can use the New-DistributionGroup cmdlet to create the following types of groups:
-
Mail-enabled universal security group (USG)
-
Universal distribution group
Distribution groups are used to consolidate groups of recipients into a single point of contact for email messages. Distribution groups aren't security principals, and therefore can't be used to assign permissions. However, you can use mail-enabled security groups to assign permissions.
You need to be assigned permissions before you can run this cmdlet. Although all parameters for this cmdlet are listed in this topic, you may not have access to some parameters if they're not included in the permissions assigned to you. To see what permissions you need, see the "Distribution groups" entry in the Recipients Permissions topic.
| Parameter | Required | Type | Description | ||
|---|---|---|---|---|---|
| Name | Required | System.String | The Name parameter specifies the name for the new distribution group. The value specified in the Name parameter is also used for the DisplayName parameter if the DisplayName parameter isn't specified. The Name parameter value can't exceed 64 characters.
If the values of the Name and DisplayName parameters are different:
| ||
| Alias | Optional | System.String | The Alias parameter specifies the alias of the distribution group. The Alias parameter is then used to generate the primary SMTP email address of the object. The value of Alias can contain letters, numbers and the characters !, #, $, %, &, ', *, +, -, /, =, ?, ^, _, `, {, |, } and ~. Periods (.) are allowed, but each period must be surrounded by other valid characters (for example, If the Alias parameter isn't specified, the value of the SamAccountName parameter is used to generate the primary SMTP email address, with any spaces converted to underscores. | ||
| ArbitrationMailbox | Optional | Microsoft.Exchange.Configuration.Tasks.MailboxIdParameter | This parameter is available only in on-premises Exchange 2013. The ArbitrationMailbox parameter specifies the mailbox used to manage the moderation process. This parameter accepts the following values:
| ||
| BypassNestedModerationEnabled | Optional | System.Boolean | The BypassNestedModerationEnabled parameter specifies whether to allow the parent group moderators to provide approval for any nested groups that are also moderated. If you set this parameter to
| ||
| Confirm | Optional | System.Management.Automation.SwitchParameter | The Confirm switch can be used to suppress the confirmation prompt that appears by default when this cmdlet is run. To suppress the confirmation prompt, use the syntax | ||
| CopyOwnerToMember | Optional | System.Management.Automation.SwitchParameter | The CopyOwnerToMember switch specifies that a recipient specified in the ManagedBy parameter is also a member of the distribution group. | ||
| DisplayName | Optional | System.String | The DisplayName parameter specifies the name of the distribution group in the EAC and in the Exchange GAL. If the DisplayName parameter isn't specified, the value of the Name parameter is used for the DisplayName parameter. | ||
| DomainController | Optional | Microsoft.Exchange.Data.Fqdn | This parameter is available only in on-premises Exchange 2013. The DomainController parameter specifies the fully qualified domain name (FQDN) of the domain controller that writes this configuration change to Active Directory. | ||
| ExternalDirectoryObjectId | Optional | System.String | This parameter is reserved for internal Microsoft use. | ||
| IgnoreNamingPolicy | Optional | System.Management.Automation.SwitchParameter | The IgnoreNamingPolicy switch specifies that the naming policy defined in the DistributionGroupNamingPolicy parameter of the Set-OrganizationConfig cmdlet can be ignored. You don't need to specify a value with this switch. | ||
| ManagedBy | Optional | Microsoft.Exchange.Data.MultiValuedProperty | The ManagedBy parameter specifies the name of the mailbox recipient or Active Directory user that appears in the Managed by tab of the Active Directory object. If this parameter isn't specified, the creator of the group is the owner. This parameter accepts the following values:
To specify an Active Directory user, use one of the following values:
The recipients specified with the ManagedBy parameter aren't members of the distribution group. If you want recipients specified in this parameter to be added as members of the distribution group, use the CopyOwnerToMember parameter. | ||
| MemberDepartRestriction | Optional | Microsoft.Exchange.Data.Directory.Recipient.MemberUpdateType | The MemberDepartRestriction parameter specifies the restrictions that you put on requests to leave the group. Valid values are:
| ||
| MemberJoinRestriction | Optional | Microsoft.Exchange.Data.Directory.Recipient.MemberUpdateType | The MemberJoinRestriction parameter specifies the restrictions that you put on requests to join the group. Valid values are:
| ||
| Members | Optional | Microsoft.Exchange.Data.MultiValuedProperty | The Members parameter specifies the initial list of recipients or Active Directory users who are a part of this distribution group. This parameter accepts the following values:
To specify an Active Directory user, use one of the following values:
| ||
| ModeratedBy | Optional | Microsoft.Exchange.Data.MultiValuedProperty | The ModeratedBy parameter specifies the users who are responsible for moderating the messages sent to this distribution group. To designate more than one user, separate the users by commas. The ModeratedBy parameter is required if you set the ModerationEnabled parameter to | ||
| ModerationEnabled | Optional | System.Boolean | The ModerationEnabled parameter specifies whether to enable moderation for the distribution group. To ensure moderation, set this parameters to The default value is | ||
| Notes | Optional | System.String | The Notes parameter specifies additional information about the distribution group. | ||
| Organization | Optional | Microsoft.Exchange.Configuration.Tasks.OrganizationIdParameter | The Organization parameter is reserved for internal Microsoft use. | ||
| OrganizationalUnit | Optional | Microsoft.Exchange.Configuration.Tasks.OrganizationalUnitIdParameter | The OrganizationalUnit parameter specifies the container where the distribution group is created. | ||
| OverrideRecipientQuotas | Optional | System.Management.Automation.SwitchParameter | This parameter is reserved for internal Microsoft use. | ||
| PrimarySmtpAddress | Optional | Microsoft.Exchange.Data.SmtpAddress | The PrimarySmtpAddress parameter specifies the primary return SMTP email address for the distribution group. This parameter has meaning only if the distribution group has multiple SMTP email addresses. | ||
| RoomList | Optional | System.Management.Automation.SwitchParameter | The RoomList switch specifies that all members of the distribution group are room resource mailboxes. You can create a distribution group for an office building in your organization and add all the rooms in that building to the distribution group. Room list distribution groups are then used to generate a list of building locations in Microsoft Outlook 2010 so the user can select a building and get information about when rooms are available in that building, without having to add the rooms in that building individually. | ||
| SamAccountName | Optional | System.String | This parameter is available only in on-premises Exchange 2013. The SamAccountName parameter specifies the name for clients of the object running older operating systems. The SamAccountName parameter is displayed in Active Directory. If the Alias parameter isn't specified, the following conditions are true:
| ||
| SendModerationNotifications | Optional | Microsoft.Exchange.Data.Directory.Recipient.TransportModerationNotificationFlags | The SendModerationNotifications parameter specifies whether status notifications are sent to users when they send a message to the moderated distribution group. You can specify one of the following values:
Set this parameter to Set this parameter to Set this parameter to
The default value is | ||
| Type | Optional | Microsoft.Exchange.Management.RecipientTasks.GroupType | The Type parameter specifies the group type created in Active Directory. The group's scope is always Universal. Valid values are | ||
| WhatIf | Optional | System.Management.Automation.SwitchParameter | The WhatIf switch instructs the command to simulate the actions that it would take on the object. By using the WhatIf switch, you can view what changes would occur without having to apply any of those changes. You don't have to specify a value with the WhatIf switch. |
To see the input types that this cmdlet accepts, see Cmdlet Input and Output Types. If the Input Type field for a cmdlet is blank, the cmdlet doesn’t accept input data.
To see the return types, which are also known as output types, that this cmdlet accepts, see Cmdlet Input and Output Types. If the Output Type field is blank, the cmdlet doesn’t return data.

Important: