Distribution groups and EWS in Exchange

Learn about the different types of distribution groups that are available in Exchange and how you can manage them in your EWS Managed API or EWS application.

A distribution group is a collection of email addresses that are associated with a single alias or email address. Distribution groups (also sometimes called distribution lists) enable a user to send email to multiple people by using a single recipient address. Because distribution group membership, and therefore the message recipients, can be managed outside of individual email threads, distribution groups provide an excellent way to enable the distribution of mail to a group of users. You can programmatically create and manage distribution groups by using the EWS Managed API, EWS, and the Exchange Management Shell. Before you start programming, let's explore the different types of distribution groups that are available and your options for managing them.

Types of distribution groups

Exchange supports three types of distribution groups:

  • Universal distribution groups — Active Directory universal distribution group objects that are mail-enabled. Universal distribution groups are used to distribute messages to a group of recipients.

  • Security groups — Active Directory objects that are mail-enabled; also known as universal security groups. Security groups are used to assign access permissions to resources in Active Directory Domain Services (AD DS) as well as to distribute messages.

  • Contact groups — Private distribution groups that are located in a user's mailbox.

The type of distribution group that you choose will depend on where you plan to store the distribution group, who will use it, and what it will be used for.

Universal distribution groups

You can use universal distribution groups to consolidate groups of recipients into a single alias or email address. Because universal distribution groups are stored in AD DS, anyone can use them to send email, including users outside your organization. You can use the EWS Managed API or EWS to expand a distribution group, but to create and manage distribution groups, you'll need to use Exchange Management Shell cmdlets.

You can also use universal distribution groups to contain a collection of rooms; for example, to make it easier for users to find a conference room for a meeting. Users can add a room list — a universal distribution group that contains room resource mailboxes — to a meeting request to find an available room without having to add each room individually.

You can create a static universal distribution group that stays the same until you to update the membership, or you can create a dynamic universal distribution group. A dynamic universal 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.

Security groups

Universal distribution groups and security groups are identical in most ways. However, unlike universal distribution groups, you can use security groups to assign permissions to network resources in AD DS. You cannot use the EWS Managed API or EWS to create and manage security groups; instead, you use Exchange Management Shell cmdlets. But, just like universal distribution groups, you can use the EWS Managed API or EWS to expand security groups.

Contact groups

If you don't want to give every user administrative access to the server to create distribution groups, but you want to enable them to send a single message to a large collection of people, you can do this by using contact groups. A contact group does not have an email address associated with it, and it exists only in one user's mailbox; other users won't have access to it. You can use the EWS Managed API or EWS to create contact groups.

Managing distribution groups by using the EWS Managed API or EWS

You can use the EWS Managed API or EWS to expand a universal distribution group or security group and to control the creation and management of a contact group; however, you cannot use these technologies to create or edit the members of those groups.

Table 1. EWS Managed API methods and EWS operations for managing distribution groups

EWS Managed API method EWS operation Use to…
ContactGroup class methods
CreateItem
Create a contact group in the Exchange store.

NOTE: You cannot create a universal distribution group or security group by using EWS Managed API or EWS.
ExpandGroup
ExpandDL
Expand a universal distribution group, security group, or contact group by retrieving a list of its members.
FindItems
FindItem
Search for contact groups in the mailbox.
GetRooms
GetRooms
Retrieve a collection of all rooms in a specified room list in an organization. A room list is a distribution group that only contains room resource mailboxes.
ResolveName
ResolveNames
Search for and return possible candidates to match an ambiguous name. The candidates can be distribution groups.

You can use the information returned by the ExpandGroup method or the ExpandDL operation to determine what types of members are in the group. The member types are defined by the MailboxType EWS Managed API enumeration and the MailboxType EWS element.

Table 2. Distribution group member types

MailboxType enumeration value MailboxType element value Description
Mailbox
Mailbox
A mail-enabled Active Directory object.
PublicGroup
PublicDL
A distribution group contained within the group you just expanded. To get a full list of members, expand this group as well.
ContactGroup
PrivateDL
A group of contacts that is located in the mailbox and is only available to users of that mailbox.
Contact
Contact
An Exchange database contact or Active Directory mail contact.

Managing distribution groups by using the Exchange Management Shell

You can use Exchange Management Shell cmdlets to create and manage universal distribution groups and security groups in your code.

Note

You cannot use Exchange Management Shell cmdlets to manage contact groups.

Table 3. Exchange Management Shell cmdlets for working with distribution groups

Cmdlet Use to…
Disable-DistributionGroup
Remove mail capabilities from a mail-enabled distribution group.
Enable-DistributionGroup
Mail-enable an existing universal group.
Get-DistributionGroup
Query for existing distribution groups.
New-DistributionGroup
Create a distribution group.
Remove-DistributionGroup
Delete an existing distribution group from AD DS.
Set-DistributionGroup
Modify the settings of an existing distribution group.
Add-DistributionGroupMember
Add a recipient to a distribution group.
Get-DistributionGroupMember
Find existing distribution group members.
Remove-DistributionGroupMember
Remove an existing recipient from a distribution group.
Update-DistributionGroupMember
Update a member of a specified distribution group.
Get-DynamicDistributionGroup
Retrieve the settings on an existing dynamic distribution group.
New-DynamicDistributionGroup
Create a dynamic distribution group.
Remove-DynamicDistributionGroup
Delete an existing dynamic distribution group. This cmdlet removes the dynamic distribution group from AD DS.
Set-DynamicDistributionGroup
Modify the settings of an existing dynamic distribution group.

In this section

See also