Applies to: Exchange Server 2010 SP3, Exchange Server 2010 SP2

Topic Last Modified: 2012-11-16

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

Syntax

New-DynamicDistributionGroup -Name <String> -IncludedRecipients <None | MailboxUsers | Resources | MailContacts | MailGroups | MailUsers | AllRecipients> [-Alias <String>] [-ArbitrationMailbox <MailboxIdParameter>] [-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>] [-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>]]
New-DynamicDistributionGroup -Name <String> -RecipientFilter <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>]]

Detailed Description

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 e-mail 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 Mailbox Permissions topic.

Parameters

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 and also in the Group Name field in the Exchange Management Console.

  • The DisplayName parameter specifies the dynamic distribution group name in the Exchange Management Console 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.

For more information about the filterable properties, see Filterable Properties for the -RecipientFilter Parameter.

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 e-mail 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

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

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

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

This parameter is available for multi-tenant deployments. It isn't available for on-premises deployments. For more information about multi-tenant deployments, see Multi-Tenant Support.

The Organization parameter specifies the organization in which you'll perform this action. This parameter doesn't accept wildcard characters, and you must use the exact name of the organization.

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 available for multi-tenant deployments. It isn't available for on-premises deployments. For more information about multi-tenant deployments, see Multi-Tenant Support.

The OverrideRecipientQuotas parameter specifies that the recipient quotas for this group can be overridden. Groups that are part of a tenant organization will use the quotas defined in the tenant organization's service plan. Use this parameter to allow the command to skip the tenant-level recipient quotas check.

Note:
Using this parameter doesn't set quotas. You need to define the quotas for the group using the appropriate Set cmdlet.

PrimarySmtpAddress

Optional

Microsoft.Exchange.Data.SmtpAddress

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

Note:
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.

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.

Examples

EXAMPLE 1

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

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

EXAMPLE 2

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

Copy Code 
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"