Applies to: Exchange Server 2013, Exchange Online

Topic Last Modified: 2012-12-18

Use the New-DistributionGroup cmdlet to create a distribution group.

For information about the parameter sets in the Syntax section below, see Syntax.

Syntax

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>]]

Examples

EXAMPLE 1

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.

Copy Code 
New-DistributionGroup -Name "Managers" -OrganizationalUnit "contoso.com/Users" -SamAccountName "Managers" -Type "Security"

EXAMPLE 2

This example creates the distribution group ITDepartment and ignores the naming policy.

Copy Code 
New-DistributionGroup -Name "ITDepartment" -IgnoreNamingPolicy

Detailed Description

You can use the New-DistributionGroup cmdlet to create Active Directory group objects of the following types:

  • 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 can't be used to assign permissions to network resources in Active Directory.

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.

Parameters

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.

Note:
If a group naming policy is enforced, you need to follow the naming constraints specified in the DistributionGroupNameBlockedWordList and the DistributionGroupNamingPolicy parameters of the Set-OrganizationConfig cmdlet.

If the values of the Name and DisplayName parameters are different:

  • The Name parameter specifies the distribution group name in Active Directory Users and Computers.

  • The DisplayName parameter specifies the distribution group name in the Exchange Administration Center (EAC) and in the Exchange global address list (GAL).

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 the Alias parameter can't contain spaces. 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

The ArbitrationMailbox parameter specifies the mailbox used to manage the moderation process.

This parameter accepts the following values:

  • Alias

    Example: JPhillips

  • Canonical DN

    Example: Atlanta.Corp.Contoso.Com/Users/JPhillips

  • Display Name

    Example: Jeff Phillips

  • Distinguished Name (DN)

    Example: CN=JPhillips,CN=Users,DC=Atlanta,DC=Corp,DC=contoso,DC=com

  • Domain\Account

    Example: Atlanta\JPhillips

  • GUID

    Example: fb456636-fe7d-4d58-9d15-5af57d0354c2

  • Immutable ID

    Example: fb456636-fe7d-4d58-9d15-5af57d0354c2@contoso.com

  • Legacy Exchange DN

    Example: /o=Contoso/ou=AdministrativeGroup/cn=Recipients/cn=JPhillips

  • SMTP Address

    Example: Jeff.Phillips@contoso.com

  • User Principal Name

    Example: JPhillips@contoso.com

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 $true, after a moderator approves a message sent to this distribution group, the message is automatically approved for any other moderated recipients that are members of this distribution group. The default value is $false.

Note:
This parameter can be set only by top-level organization and tenant administrators.

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 -Confirm:$False. You must include a colon ( : ) in the syntax.

CopyOwnerToMember

Optional

System.Management.Automation.SwitchParameter

The CopyOwnerToMember parameter 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

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 parameter 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 parameter.

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:

  • Alias

    Example: JPhillips

  • Canonical DN

    Example: Atlanta.Corp.Contoso.Com/Users/JPhillips

  • Display Name

    Example: Jeff Phillips

  • Distinguished Name (DN)

    Example: CN=JPhillips,CN=Users,DC=Atlanta,DC=Corp,DC=contoso,DC=com

  • Domain\Account

    Example: Atlanta\JPhillips

  • GUID

    Example: fb456636-fe7d-4d58-9d15-5af57d0354c2

  • Immutable ID

    Example: fb456636-fe7d-4d58-9d15-5af57d0354c2@contoso.com

  • Legacy Exchange DN

    Example: /o=Contoso/ou=AdministrativeGroup/cn=Recipients/cn=JPhillips

  • SMTP Address

    Example: Jeff.Phillips@contoso.com

  • User Principal Name

    Example: JPhillips@contoso.com

To specify an Active Directory user, use one of the following values:

  • GUID

  • DN

  • UPN

  • Domain\Account Name

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 can put on recipients who want to depart the group membership. This parameter can take one of the following values:

  • Open

  • Closed

  • ApprovalRequired

Note:
Universal security groups can't use the Open value. By default, they're set to Closed.

MemberJoinRestriction

Optional

Microsoft.Exchange.Data.Directory.Recipient.MemberUpdateType

The MemberJoinRestriction parameter specifies the restrictions that you can put on recipients who want to join the group membership. This parameter can take one of the following values:

  • Open

  • Closed

  • ApprovalRequired

Note:
Universal security groups can't use the Open value. By default, they're set to Closed.

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:

  • Alias

    Example: JPhillips

  • Canonical DN

    Example: Atlanta.Corp.Contoso.Com/Users/JPhillips

  • Display Name

    Example: Jeff Phillips

  • Distinguished Name (DN)

    Example: CN=JPhillips,CN=Users,DC=Atlanta,DC=Corp,DC=contoso,DC=com

  • Domain\Account

    Example: Atlanta\JPhillips

  • GUID

    Example: fb456636-fe7d-4d58-9d15-5af57d0354c2

  • Immutable ID

    Example: fb456636-fe7d-4d58-9d15-5af57d0354c2@contoso.com

  • Legacy Exchange DN

    Example: /o=Contoso/ou=AdministrativeGroup/cn=Recipients/cn=JPhillips

  • SMTP Address

    Example: Jeff.Phillips@contoso.com

  • User Principal Name

    Example: JPhillips@contoso.com

To specify an Active Directory user, use one of the following values:

  • GUID

  • DN

  • UPN

  • Domain\Account Name

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 $true. If you leave this parameter blank and there is a user already specified as the manager of this distribution group, the ModeratedBy field is automatically set to the ManagedBy parameter of the distribution group. Otherwise, an error is returned.

ModerationEnabled

Optional

System.Boolean

The ModerationEnabled parameter specifies whether to enable moderation for the distribution group. To ensure moderation, set this parameters to $true. To disable moderation, set this parameter to $false.

The default value is $false.

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 parameter specifies that all members of the distribution group are room resource mailboxes. You can create a distribution list 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

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:

  • The value of the SamAccountName parameter is used for the value of the Alias parameter, with any spaces converted to underscores.

  • The SamAccountName parameter, with any spaces converted to underscores, is used to generate the primary SMTP email address of the object.

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:

  • Always

  • Internal

  • Never

Set this parameter to Always if you want notifications to be sent to all senders.

Set this parameter to Internal if you want notifications to be sent only to the senders who are internal to your organization.

Set this parameter to Never to disable all status notifications.

Note:
The senders are always notified if their message is rejected by the moderators, regardless of the value of the parameter.

The default value is Never.

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 Distribution or Security.

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.

Input Types

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.

Return Types

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.