Export (0) Print
Expand All

New-DynamicDistributionGroup

 

Applies to: Exchange Server 2013, Exchange Online

Topic Last Modified: 2014-03-12

This cmdlet is available in on-premises Exchange Server 2013 and in the cloud-based service. Some parameters and settings may be exclusive to one environment or the other.

Use the New-DynamicDistributionGroup cmdlet to create a dynamic distribution group.

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

New-DynamicDistributionGroup -RecipientFilter <String> <COMMON PARAMETERS>
New-DynamicDistributionGroup -IncludedRecipients <None | MailboxUsers | Resources | MailContacts | MailGroups | MailUsers | AllRecipients> [-ConditionalCompany <MultiValuedProperty>] [-ConditionalCustomAttribute1 <MultiValuedProperty>] [-ConditionalCustomAttribute10 <MultiValuedProperty>] [-ConditionalCustomAttribute11 <MultiValuedProperty>] [-ConditionalCustomAttribute12 <MultiValuedProperty>] [-ConditionalCustomAttribute13 <MultiValuedProperty>] [-ConditionalCustomAttribute14 <MultiValuedProperty>] [-ConditionalCustomAttribute15 <MultiValuedProperty>] [-ConditionalCustomAttribute2 <MultiValuedProperty>] [-ConditionalCustomAttribute3 <MultiValuedProperty>] [-ConditionalCustomAttribute4 <MultiValuedProperty>] [-ConditionalCustomAttribute5 <MultiValuedProperty>] [-ConditionalCustomAttribute6 <MultiValuedProperty>] [-ConditionalCustomAttribute7 <MultiValuedProperty>] [-ConditionalCustomAttribute8 <MultiValuedProperty>] [-ConditionalCustomAttribute9 <MultiValuedProperty>] [-ConditionalDepartment <MultiValuedProperty>] [-ConditionalStateOrProvince <MultiValuedProperty>] <COMMON PARAMETERS>
COMMON PARAMETERS: -Name <String> [-Alias <String>] [-ArbitrationMailbox <MailboxIdParameter>] [-Confirm [<SwitchParameter>]] [-DisplayName <String>] [-DomainController <Fqdn>] [-ExternalDirectoryObjectId <String>] [-ModeratedBy <MultiValuedProperty>] [-ModerationEnabled <$true | $false>] [-Organization <OrganizationIdParameter>] [-OrganizationalUnit <OrganizationalUnitIdParameter>] [-OverrideRecipientQuotas <SwitchParameter>] [-PrimarySmtpAddress <SmtpAddress>] [-RecipientContainer <OrganizationalUnitIdParameter>] [-SendModerationNotifications <Never | Internal | Always>] [-WhatIf [<SwitchParameter>]]

This example creates the dynamic distribution group Marketing Group in the Users container in the contoso.com domain. The Marketing Group dynamic distribution group contains all mailbox users or mail-enabled contacts found anywhere in the contoso.com domain who have a Department field that equals the strings "Marketing" or "Sales".

New-DynamicDistributionGroup -Name "Marketing Group" -Alias "Marketing_Group" -IncludedRecipients "MailboxUsers,MailContacts" -OrganizationalUnit "contoso.com/Users" -ConditionalDepartment "Marketing","Sales" -RecipientContainer "contoso.com"

This example uses the RecipientFilter parameter to create the dynamic distribution group Pacific Northwest in the Users container in the contoso.com domain. The Pacific Northwest dynamic distribution group contains all mailbox users found anywhere in the contoso.com domain who have a State/Province field that equals "Washington" or "Oregon".

New-DynamicDistributionGroup -Name "Pacific Northwest" -Alias "Pacific_Northwest" -OrganizationalUnit "contoso.com/Users" -RecipientFilter {((RecipientType -eq 'UserMailbox') -and ((StateOrProvince -eq 'Washington' -or StateOrProvince -eq 'Oregon')))} -RecipientContainer "contoso.com"

A dynamic distribution group queries Active Directory mail-enabled objects and builds the group membership based on the results. The group membership is recalculated whenever an email message is sent to the group. The query filters provided with Microsoft Exchange are limited to any combination of the following parameters:

  • ConditionalCompany

  • ConditionalCustomAttribute N (where N is a value from 1 through 15)

  • ConditionalDepartment

  • ConditionalStateOrProvince

  • IncludedRecipients

You can also create any custom query using the RecipientFilter parameter.

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 "Dynamic distribution groups" entry in the Recipients Permissions topic.

 

Parameter Required Type Description

IncludedRecipients

Required

Microsoft.Exchange.Data.Directory.Recipient.WellKnownRecipientType

The IncludedRecipients parameter filters the recipient types used to build the dynamic distribution group. The IncludedRecipients parameter can't be used if the RecipientFilter parameter is specified. You can use the following values:

  • AllRecipients

  • MailboxUsers

  • Resources

  • MailContacts

  • MailGroups

  • MailUsers

  • None

AllRecipients can be used only by itself. When multiple values in the IncludedRecipients parameter are separated by commas, the OR Boolean operator is applied.

Name

Required

System.String

The Name parameter specifies the name of the dynamic distribution group. If the DisplayName parameter isn't specified, the value of the Name parameter is also used for the DisplayName parameter.

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 dynamic distribution group name in Active Directory Users and Computers.

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

RecipientFilter

Required

System.String

The RecipientFilter parameter filters the mail-enabled recipients used to build the dynamic distribution group. The RecipientFilter parameter can't be used if any of the following parameters are specified:

  • IncludedRecipients

  • ConditionalCompany

  • ConditionalCustomAttribute N (where N is a value from 1 through 15)

  • ConditionalDepartment

  • ConditionalStateOrProvince

The RecipientFilter parameter uses OPath syntax to query Active Directory and filter recipients.

Alias

Optional

System.String

The Alias parameter specifies the alias of the dynamic distribution group. The value of the Alias parameter is used to generate the primary SMTP email address for the dynamic distribution group. The value of the Alias parameter can't contain spaces. If the Alias parameter isn't specified, the value of the Name parameter is used for the value of the Alias parameter, with any spaces in the Name parameter converted to underscore characters (_).

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.

ConditionalCompany

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ConditionalCompany parameter filters the mailbox users or mail-enabled contacts used to build the dynamic distribution group.

When multiple values of the ConditionalCompany parameter are separated by commas, the OR Boolean operator is applied.

ConditionalCustomAttribute1

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ConditionalCustomAttribute1 to ConditionalCustomAttribute15 parameters specify filters for recipients' custom attributes. For example, if you set the ConditionalCustomAttribute1 value to Marketing, all included recipients whose CustomAttribute1 value is Marketing are included in this filter. You must use the IncludedRecipients parameter if you use a Conditional parameter. You can't use this parameter if you use the RecipientFilter parameter.

ConditionalCustomAttribute10

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ConditionalCustomAttribute1 to ConditionalCustomAttribute15 parameters specify filters for recipients' custom attributes. For example, if you set the ConditionalCustomAttribute1 value to Marketing, all included recipients whose CustomAttribute1 value is Marketing are included in this filter. You must use the IncludedRecipients parameter if you use a Conditional parameter. You can't use this parameter if you use the RecipientFilter parameter.

ConditionalCustomAttribute11

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ConditionalCustomAttribute1 to ConditionalCustomAttribute15 parameters specify filters for recipients' custom attributes. For example, if you set the ConditionalCustomAttribute1 value to Marketing, all included recipients whose CustomAttribute1 value is Marketing are included in this filter. You must use the IncludedRecipients parameter if you use a Conditional parameter. You can't use this parameter if you use the RecipientFilter parameter.

ConditionalCustomAttribute12

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ConditionalCustomAttribute1 to ConditionalCustomAttribute15 parameters specify filters for recipients' custom attributes. For example, if you set the ConditionalCustomAttribute1 value to Marketing, all included recipients whose CustomAttribute1 value is Marketing are included in this filter. You must use the IncludedRecipients parameter if you use a Conditional parameter. You can't use this parameter if you use the RecipientFilter parameter.

ConditionalCustomAttribute13

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ConditionalCustomAttribute1 to ConditionalCustomAttribute15 parameters specify filters for recipients' custom attributes. For example, if you set the ConditionalCustomAttribute1 value to Marketing, all included recipients whose CustomAttribute1 value is Marketing are included in this filter. You must use the IncludedRecipients parameter if you use a Conditional parameter. You can't use this parameter if you use the RecipientFilter parameter.

ConditionalCustomAttribute14

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ConditionalCustomAttribute1 to ConditionalCustomAttribute15 parameters specify filters for recipients' custom attributes. For example, if you set the ConditionalCustomAttribute1 value to Marketing, all included recipients whose CustomAttribute1 value is Marketing are included in this filter. You must use the IncludedRecipients parameter if you use a Conditional parameter. You can't use this parameter if you use the RecipientFilter parameter.

ConditionalCustomAttribute15

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ConditionalCustomAttribute1 to ConditionalCustomAttribute15 parameters specify filters for recipients' custom attributes. For example, if you set the ConditionalCustomAttribute1 value to Marketing, all included recipients whose CustomAttribute1 value is Marketing are included in this filter. You must use the IncludedRecipients parameter if you use a Conditional parameter. You can't use this parameter if you use the RecipientFilter parameter.

ConditionalCustomAttribute2

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ConditionalCustomAttribute1 to ConditionalCustomAttribute15 parameters specify filters for recipients' custom attributes. For example, if you set the ConditionalCustomAttribute1 value to Marketing, all included recipients whose CustomAttribute1 value is Marketing are included in this filter. You must use the IncludedRecipients parameter if you use a Conditional parameter. You can't use this parameter if you use the RecipientFilter parameter.

ConditionalCustomAttribute3

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ConditionalCustomAttribute1 to ConditionalCustomAttribute15 parameters specify filters for recipients' custom attributes. For example, if you set the ConditionalCustomAttribute1 value to Marketing, all included recipients whose CustomAttribute1 value is Marketing are included in this filter. You must use the IncludedRecipients parameter if you use a Conditional parameter. You can't use this parameter if you use the RecipientFilter parameter.

ConditionalCustomAttribute4

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ConditionalCustomAttribute1 to ConditionalCustomAttribute15 parameters specify filters for recipients' custom attributes. For example, if you set the ConditionalCustomAttribute1 value to Marketing, all included recipients whose CustomAttribute1 value is Marketing are included in this filter. You must use the IncludedRecipients parameter if you use a Conditional parameter. You can't use this parameter if you use the RecipientFilter parameter.

ConditionalCustomAttribute5

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ConditionalCustomAttribute1 to ConditionalCustomAttribute15 parameters specify filters for recipients' custom attributes. For example, if you set the ConditionalCustomAttribute1 value to Marketing, all included recipients whose CustomAttribute1 value is Marketing are included in this filter. You must use the IncludedRecipients parameter if you use a Conditional parameter. You can't use this parameter if you use the RecipientFilter parameter.

ConditionalCustomAttribute6

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ConditionalCustomAttribute1 to ConditionalCustomAttribute15 parameters specify filters for recipients' custom attributes. For example, if you set the ConditionalCustomAttribute1 value to Marketing, all included recipients whose CustomAttribute1 value is Marketing are included in this filter. You must use the IncludedRecipients parameter if you use a Conditional parameter. You can't use this parameter if you use the RecipientFilter parameter.

ConditionalCustomAttribute7

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ConditionalCustomAttribute1 to ConditionalCustomAttribute15 parameters specify filters for recipients' custom attributes. For example, if you set the ConditionalCustomAttribute1 value to Marketing, all included recipients whose CustomAttribute1 value is Marketing are included in this filter. You must use the IncludedRecipients parameter if you use a Conditional parameter. You can't use this parameter if you use the RecipientFilter parameter.

ConditionalCustomAttribute8

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ConditionalCustomAttribute1 to ConditionalCustomAttribute15 parameters specify filters for recipients' custom attributes. For example, if you set the ConditionalCustomAttribute1 value to Marketing, all included recipients whose CustomAttribute1 value is Marketing are included in this filter. You must use the IncludedRecipients parameter if you use a Conditional parameter. You can't use this parameter if you use the RecipientFilter parameter.

ConditionalCustomAttribute9

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ConditionalCustomAttribute1 to ConditionalCustomAttribute15 parameters specify filters for recipients' custom attributes. For example, if you set the ConditionalCustomAttribute1 value to Marketing, all included recipients whose CustomAttribute1 value is Marketing are included in this filter. You must use the IncludedRecipients parameter if you use a Conditional parameter. You can't use this parameter if you use the RecipientFilter parameter.

ConditionalDepartment

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ConditionalDepartment parameter filters the mailbox users or mail-enabled contacts used to build the dynamic distribution group. The ConditionalDepartment parameter can't be used if the RecipientFilter parameter is specified.

When multiple values of the ConditionalDepartment parameter are separated by commas, the OR Boolean operator is applied.

ConditionalStateOrProvince

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ConditionalStateOrProvince parameter filters mailbox users or mail-enabled contacts used to build the dynamic distribution group. The ConditionalStateOrProvince parameter can't be used if the RecipientFilter parameter is specified.

When multiple values of the ConditionalStateOrProvince parameter are separated by commas, the OR Boolean operator is applied.

Confirm

Optional

System.Management.Automation.SwitchParameter

The Confirm switch causes the command to pause processing and requires you to acknowledge what the command will do before processing continues. You don't have to specify a value with the Confirm switch.

DisplayName

Optional

System.String

The DisplayName parameter specifies the name of the dynamic distribution group in the Exchange Administration Center 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.

ModeratedBy

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ModeratedBy parameter specifies the users who are responsible for moderating the messages sent to this dynamic distribution group. To designate more than one user, separate the users with commas.

This parameter is required if you set the ModerationEnabled parameter to $true.

ModerationEnabled

Optional

System.Boolean

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

The default value is $false.

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 where to create the dynamic distribution group in Active Directory by using canonical name syntax.

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 dynamic distribution group. This parameter has meaning only if the dynamic distribution group has multiple SMTP email addresses.

RecipientContainer

Optional

Microsoft.Exchange.Configuration.Tasks.OrganizationalUnitIdParameter

The RecipientContainer parameter filters the recipients used to build the dynamic distribution group based on their location in Active Directory. The value of the RecipientContainer parameter can be the canonical name of an organizational unit (OU) or a domain. If you don't specify a value for the RecipientContainer parameter, the cmdlet will default to use the local container. This location is specified by using the OrganizationalUnit parameter.

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 dynamic distribution group. You can specify one of the following values:

  • Always

  • Internal

  • Never

If you want notifications to be sent to all senders, set this parameter to Always.

If you want notifications to be sent only to the senders internal to your organization, set this parameter to Internal.

To disable all status notifications, set this parameter to Never.

NoteNote:
Senders are always notified if their message is rejected by the moderators, regardless of the value of this parameter.
The default value is Never.

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.

 
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft