New-DistributionGroup

  • Article

 

Applies to: Exchange Server 2007 SP1, Exchange Server 2007 SP2, Exchange Server 2007 SP3

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

Syntax

New-DistributionGroup -Name <String> -SamAccountName <String> -Type <Distribution | Security> [-Alias <String>] [-Confirm [<SwitchParameter>]] [-DisplayName <String>] [-DomainController <Fqdn>] [-ManagedBy <GeneralRecipientIdParameter>] [-OrganizationalUnit <OrganizationalUnitIdParameter>] [-TemplateInstance <PSObject>] [-UseRusServer <String>] [-WhatIf [<SwitchParameter>]]

Detailed Description

You can use the New-DistributionGroup cmdlet to create new 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 the Active Directory directory service.

To run the New-DistributionGroup cmdlet, the account you use must be delegated the following:

  • Exchange Recipient Administrator role

  • Account Operator role for the applicable Active Directory containers

For more information about permissions, delegating roles, and the rights that are required to administer Exchange Server 2007, see Permission Considerations.

Parameters

Parameter Required Type Description

Name

Required

System.String

This parameter specifies the name for the new distribution group. The value that is specified in the Name parameter is also used for DisplayName if the DisplayName parameter is not specified.

The Name value can't exceed 64 characters.

If the values of Name and DisplayName are different:

  • Name specifies the distribution group name in Active Directory Users and Computers and also in the Group Name field in the Exchange Management Console.

  • DisplayName specifies the distribution group name in the Exchange Management Console and in the Exchange global address list (GAL).

SamAccountName

Required

System.String

This parameter specifies the name for clients of the object that are 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 is not specified, the following conditions are true:

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

  • SAMAccountName, with any spaces converted to underscores, is used to generate the primary Simple Mail Transfer Protocol (SMTP) e-mail address of the object.

Type

Required

Microsoft.Exchange.Management.RecipientTasks.GroupType

This parameter specifies the group type that will be created in Active Directory. The group's scope is always Universal. Valid values are Distribution or Security.

Alias

Optional

System.String

This parameter can be used to specify 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 Alias can't contain spaces. If Alias is not specified, the value of SAMAccountName is used to generate the primary SMTP e-mail address, with any spaces converted to underscores.

Confirm

Optional

System.Management.Automation.SwitchParameter

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

DisplayName

Optional

System.String

This parameter can be used to specify the name of the distribution group in the Exchange Management Console and in the Exchange GAL. If the DisplayName parameter is not specified, the value of the Name parameter is used for DisplayName.

DomainController

Optional

Microsoft.Exchange.Data.Fqdn

To specify the fully qualified domain name (FQDN) of the domain controller that writes this configuration change to Active Directory, include the DomainController parameter.

ManagedBy

Optional

Microsoft.Exchange.Configuration.Tasks.GeneralRecipientIdParameter

This parameter can be used to specify the name of the mailbox user, mail-enabled group, or mail-enabled contact that appears in the Managed by tab of the Active Directory object. You can use any of the following values for this parameter:

  • Distinguished name (DN)

  • Canonical name

  • GUID

  • Name

  • Display name

  • Legacy Exchange DN

  • Primary SMTP e-mail address

OrganizationalUnit

Optional

Microsoft.Exchange.Configuration.Tasks.OrganizationalUnitIdParameter

This parameter specifies where to create the distribution group in Active Directory by using canonical name syntax.

TemplateInstance

Optional

System.Management.Automation.PSObject

When an existing object is supplied to this parameter, the cmdlet uses that object to create a copy of the object.

UseRusServer

Optional

System.String
noteNote:
This parameter is available only in Exchange Server 2007 SP2.

The UseRusServer parameter instructs the command to use the specified Mailbox server on which the Address List service is running to obtain and then set mailbox and Active Directory user attributes.

The Address List service is a component in the Exchange System Attendant service. The Address List service creates and maintains Exchange-specific attribute values in Active Directory. You can use the Address List service to update recipient objects in a domain by using specific information, such as address list membership and e-mail addresses.

WhatIf

Optional

System.Management.Automation.SwitchParameter

The WhatIf parameter instructs the command to simulate the actions that it would take on the object. By using the WhatIf parameter, 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 parameter.

Input Types

Return Types

Errors

Error Description

 

 

Exceptions

Exceptions Description

 

 

Example

The following code example shows how to use the New-DistributionGroup cmdlet to create a new mail-enabled universal security group that has the following parameters:

  • The group's name will be "Managers".

  • The group will be created in the Users container in the domain Contoso.com.

  • The group's SAM account name will be "Managers".

  • The group type will be Security.

New-DistributionGroup -Name "Managers" -OrganizationalUnit "contoso.com/Users" -SAMAccountName "Managers" -Type "Security"