DistributionGroupMember endpoint in the Exchange Online Admin API

Note

The features described in this article are currently in Preview, aren't available in all organizations, and are subject to change.

The DistributionGroupMember endpoint in the Exchange Online Admin API retrieves the members of a specified distribution group. The endpoint returns a collection of recipient objects representing group membership and related directory information.

Typical use cases include:

• Expanding distribution lists for mail routing.
• Expanding Room lists to display list of all the members.

Note

The response of this endpoint includes members who are hidden from address lists.

The Exchange Online Admin API provides a REST-based way to execute specific PowerShell cmdlets, replacing legacy Exchange Web Services (EWS) scenarios. For more information, see Overview of the Exchange Online Admin API.

Endpoint URL

POST https://outlook.office365.com/adminapi/v2.0/<TenantID>/DistributionGroupMember

Tip

Use the base URL for your environment as described in Supported environments and base URLs.

Request model

Headers

Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <routing hint>

For X-AnchorMailbox values, see X-AnchorMailbox routing hint.

Body

{
  "CmdletInput": {
    "CmdletName": "Get-DistributionGroupMember",
    "Parameters": {
      "Identity": "<distribution group identity>",    // required
      "ResultSize": <Integer | "Unlimited">           // optional (pagination)
    }
  }
}

Pagination

The ResultSize parameter controls pagination. By default, up to 1,000 results are returned.

If more results are available, the response includes an @odata.nextLink property with a continuation URL. To fetch the next page, issue a new POST request to the URL in @odata.nextLink with the same body.

Property selection

This endpoint supports the $select query parameter to return only specific properties in the response. For example:

POST https://outlook.office365.com/adminapi/v2.0/<TenantID>/DistributionGroupMember?$select=DisplayName,PrimarySmtpAddress

Supported cmdlets and parameters

The supported cmdlet for this endpoint is Get-DistributionGroupMember. Any other cmdlet in the body of this endpoint results in an error.

Only the parameters described in the following table are available through the REST endpoint:

Parameter	Required	Type	Description
Identity	Required	String	Specifies the distribution group to retrieve membership information about. Valid values are the group name, email address, or GUID. Subject to ResultSize, the cmdlet returns all group members, including hidden recipients.
ResultSize	Optional	Integer or Unlimited	Limits the number of results returned. Valid values are an integer (for example, 10) or the value "Unlimited".

Response overview

Note

During Preview, the endpoint includes the full Get-DistributionGroupMember cmdlet output in the API response. During the transition to public release, the response will be limited to the core properties listed in this section (properties needed for the EWS‑equivalent scenario). We recommend you use the properties listed in this section only. We'll document any changes to the available properties.

The response is a JSON array of group members. Each recipient object contains details and metadata information. The following properties are returned:

• Identity: Canonical identity of the recipient (used for management operations).
• Alias: Mail alias (if applicable).
• EmailAddresses: All proxy addresses for the recipient (including SMTP: and smtp: entries).
• PrimarySmtpAddress: Primary SMTP address for the recipient (corresponds to the SMTP: value in EmailAddresses).
• DisplayName: Recipient display name.
• FirstName
• LastName
• Name: Exchange display name (often mirrors DisplayName).
• RecipientType: For possible values, see RecipientType.
• RecipientTypeDetails: For possible values, see RecipientTypeDetails.
• HiddenFromAddressListsEnabled: Is the recipient hidden from membership in the distribution group.

Examples

• Example 1: Get all members of a distribution group:

  This example retrieves a maximum of 1,000 members of the specified distribution group because we aren't using the ResultSize parameter.

  POST /adminapi/v2.0/<TenantID>/DistributionGroupMember HTTP/1.1
  Host: outlook.office365.com
  Authorization: Bearer <auth token>
  Content-Type: application/json
  X-AnchorMailbox: <Routing Hint>
  
  {
    "CmdletInput": {
      "CmdletName": "Get-DistributionGroupMember",
      "Parameters": {
        "Identity": "marketing@contoso.com"
      }
    }
  }
  

• Example 2: Limit results using ResultSize:

  This example limits the results to 10 members of the specified distribution group by setting the ResultSize parameter to the value 10.

  POST /adminapi/v2.0/<TenantID>/DistributionGroupMember HTTP/1.1
  Host: outlook.office365.com
  Authorization: Bearer <auth token>
  Content-Type: application/json
  X-AnchorMailbox: <Routing Hint>>
  
  {
    "CmdletInput": {
      "CmdletName": "Get-DistributionGroupMember",
      "Parameters": {
        "Identity": "marketing@contoso.com",
        "ResultSize": 10
      }
    }
  }