Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

New-DistributionGroup

Applies to: Exchange Server 2010

Topic Last Modified: 2011-03-19

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


New-DistributionGroup -Name <String> [-Alias <String>] [-ArbitrationMailbox <MailboxIdParameter>] [-BypassNestedModerationEnabled <$true | $false>] [-Confirm [<SwitchParameter>]] [-CopyOwnerToMember <SwitchParameter>] [-DisplayName <String>] [-DomainController <Fqdn>] [-ExternalManaged <SwitchParameter>] [-ManagedBy <RecipientIdParameter[]>] [-MemberDepartRestriction <Closed | Open | ApprovalRequired>] [-MemberJoinRestriction <Closed | Open | ApprovalRequired>] [-Members <RecipientIdParameter[]>] [-ModeratedBy <MultiValuedProperty>] [-ModerationEnabled <$true | $false>] [-Notes <String>] [-Organization <OrganizationIdParameter>] [-OrganizationalUnit <OrganizationalUnitIdParameter>] [-PartnerObjectId <Guid>] [-PrimarySmtpAddress <SmtpAddress>] [-RoomList <SwitchParameter>] [-SamAccountName <String>] [-SendModerationNotifications <Never | Internal | Always>] [-Type <Distribution | Security>] [-WhatIf [<SwitchParameter>]]

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:

  • The Name parameter specifies the distribution group name in Active Directory Users and Computers and also in the Group Name field in the Exchange Management Console.
  • The DisplayName parameter specifies the distribution group name in the Exchange Management Console 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 e-mail 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 e-mail address, with any spaces converted to underscores.

ArbitrationMailbox

Optional

Microsoft.Exchange.Configuration.Tasks.MailboxIdParameter

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

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.

Aa998856.note(en-us,EXCHG.140).gifNote:
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 Exchange Management Console 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.

ExternalManaged

Optional

System.Management.Automation.SwitchParameter

The ExternalManaged parameter specifies that this distribution group is managed by an external application.

ManagedBy

Optional

Microsoft.Exchange.Configuration.Tasks.RecipientIdParameter[]

The ManagedBy parameter specifies the name of the mailbox recipient 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. You can use any of the following values for this parameter:

  • Distinguished name (DN)
  • Canonical name
  • GUID
  • Name
  • Display name
  • LegacyExchangeDN
  • Primary SMTP e-mail address

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
Aa998856.note(en-us,EXCHG.140).gifNote:
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
Aa998856.note(en-us,EXCHG.140).gifNote:
Universal security groups can't use the Open value. By default, they're set to Closed.

Members

Optional

Microsoft.Exchange.Configuration.Tasks.RecipientIdParameter[]

The Members parameter adds the initial list of members who are a part of this distribution group. You can use any of the following values for this parameter:

  • DN
  • Canonical name
  • GUID
  • Name
  • Display name
  • LegacyExchangeDN
  • Primary SMTP e-mail address

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.

PartnerObjectId

Optional

System.Guid

This parameter is reserved for internal Microsoft use.

PrimarySmtpAddress

Optional

Microsoft.Exchange.Data.SmtpAddress

The PrimarySmtpAddress parameter specifies the primary return SMTP e-mail address for the distribution group. This parameter has meaning only if the distribution group has multiple SMTP e-mail 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.

You can't use the RoomList parameter in conjunction with the ExternalManaged parameter.

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 and the Exchange Management Console in the Group name (pre-Windows 2000) field. 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 e-mail 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.

Aa998856.note(en-us,EXCHG.140).gifNote:
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 that's 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.

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

  • Mail-enabled universal security group
  • Universal distribution group

Distribution groups are used to consolidate groups of recipients into a single point of contact for e-mail 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 Mailbox Permissions topic.

Error Description

 

 

Exceptions Description

 

 

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"
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.