distributionGroups

Distribution Groups. Distribution lists and mail-enabled security groups with members and owners. The distributionGroups entity set lives under /exchange/v1.0/distributionGroups in the Recipients category.

Fact	Value
Path	`/exchange/v1.0/distributionGroups`
Category	Recipients
Tier	Tier 0, Directory
Read role	`Group.Read.All` (Community)
Write role	`Group.ReadWrite.All` (Pro)
Backing cmdlets	Get-DistributionGroup, Set-DistributionGroup, New-DistributionGroup, Remove-DistributionGroup, Add-DistributionGroupMember, Remove-DistributionGroupMember, Get-DistributionGroupMember, Update-DistributionGroupMember, Upgrade-DistributionGroup, Get-EligibleDistributionGroupForMigration

Routes

Method	Path	Synopsis	Role	Plan
GET	`/exchange/v1.0/distributionGroups`	List distributionGroups entries.	`Group.Read`	Community
POST	`/exchange/v1.0/distributionGroups`	POST /distributionGroups - creates a DL (or MESG via “type”:“Security”) via New-DistributionGroup. Returns 201 + Location + the new entity.	`Group.ReadWrite`	Pro
GET	`/exchange/v1.0/distributionGroups/eligibleForUpgrade`	GET /distributionGroups/eligibleForUpgrade - DGs eligible for M365 upgrade. Optional filters: ?identity=…, ?managedBy=….	`Group.Read`	Community
GET	`/exchange/v1.0/distributionGroups/{key}`	Get a single distributionGroups entry by Identity.	`Group.Read`	Community
PATCH	`/exchange/v1.0/distributionGroups/{key}`	PATCH /distributionGroups/{key} - partial update via Set-DistributionGroup. Cmdlet-behavior flags surfaced as query params (BypassSecurityGroupManagerCheck, IgnoreDefaultScope, IgnoreNamingPolicy, ForceUpgrade, ResetMigrationToUnifiedGroup, UpdateMemberCount). Returns 200 + the updated entity.	`Group.ReadWrite`	Pro
DELETE	`/exchange/v1.0/distributionGroups/{key}`	DELETE /distributionGroups/{key} - Remove-DistributionGroup. Use ?bypassSecurityGroupManagerCheck=true for non-owner removal of MESGs.	`Group.ReadWrite`	Pro
GET	`/exchange/v1.0/distributionGroups/{key}/members`	GET /distributionGroups/{key}/members - polymorphic members via Get-DistributionGroupMember.	`Group.Read`	Community
PUT	`/exchange/v1.0/distributionGroups/{key}/members`	PUT /distributionGroups/{key}/members - Update-DistributionGroupMember replaces the FULL member list. Empty {“members”: []} clears membership.	`Group.ReadWrite`	Pro
POST	`/exchange/v1.0/distributionGroups/{key}/members/$ref`	POST /distributionGroups/{key}/members/$ref - Add-DistributionGroupMember. Returns 204. MESG note: for a mail-enabled SECURITY group, EXO requires the caller to be a group manager (ManagedBy). App-only / non-manager principals get 403 (“This operation can only be performed by a manager of the group”) unless you pass ?bypassSecurityGroupManagerCheck=true.	`Group.ReadWrite`	Pro
DELETE	`/exchange/v1.0/distributionGroups/{key}/members/{memberId}/$ref`	DELETE /distributionGroups/{key}/members/{memberId}/$ref - Remove-DistributionGroupMember.	`Group.ReadWrite`	Pro
GET	`/exchange/v1.0/distributionGroups/{key}/owners`	GET /distributionGroups/{key}/owners - owners are the ManagedBy identities; resolve each via Get-Recipient. No dedicated owner cmdlet exists.	`Group.Read`	Community
POST	`/exchange/v1.0/distributionGroups/{key}/upgrade`	POST /distributionGroups/{key}/upgrade - Upgrade-DistributionGroup (EXO-only). Operationally async server-side; poll GET /distributionGroups/{key} for state.	`Group.ReadWrite`	Pro

GET /exchange/v1.0/distributionGroups

List distributionGroups entries.

Backing cmdlet: Get-DistributionGroup. Role: Group.Read (Community).

Parameter	In	Type	Required	Description
`all`	query	bool (switch)		Return all results instead of the EXO default of 1000. Maps -ResultSize Unlimited on Get-DistributionGroup; prevents silent truncation in large tenants.
`anr`	query	string		Ambiguous name resolution: partial-match search across common name properties. Maps -Anr on Get-DistributionGroup.

List distribution groups

Returns classic distribution lists + mail-enabled security groups (MESG). Use $filter to scope by group type, $select to project fields.

GET /exchange/v1.0/distributionGroups?$top=2&$select=Id,DisplayName,PrimarySmtpAddress,Alias,WhenCreated HTTP/1.1
Authorization: Bearer {token}

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#distributionGroups(Id,DisplayName,PrimarySmtpAddress,Alias,WhenCreated)",
  "value": [
    {
      "Id": "197c9ca8-ce81-41d4-97e2-2a06878298a8",
      "DisplayName": "Sales Team",
      "Alias": "sales-team",
      "PrimarySmtpAddress": "sales-team@contoso.com",
      "WhenCreated": "2026-03-30T17:47:41+03:00"
    },
    {
      "Id": "25568ef0-62da-405c-b0bf-a9aaa22470a9",
      "DisplayName": "IT Helpdesk All",
      "Alias": "it-helpdesk-all",
      "PrimarySmtpAddress": "it-helpdesk-all@contoso.com",
      "WhenCreated": "2026-03-30T17:47:31+03:00"
    }
  ]
}

Notes: RecipientTypeDetails discriminates: MailUniversalDistributionGroup (standard DL), MailUniversalSecurityGroup (MESG), RoomList.

POST /exchange/v1.0/distributionGroups

POST /distributionGroups - creates a DL (or MESG via “type”:“Security”) via New-DistributionGroup. Returns 201 + Location + the new entity.

Backing cmdlet: New-DistributionGroup. Role: Group.ReadWrite (Pro).

Parameter	In	Type	Required
`name`	body		yes
`alias`	body
`arbitrationMailbox`	body
`bccBlocked`	body
`bypassNestedModerationEnabled`	body
`copyOwnerToMember`	body	boolean (switch)
`description`	body
`displayName`	body
`hiddenGroupMembershipEnabled`	body	boolean (switch)
`ignoreNamingPolicy`	body	boolean (switch)
`managedBy`	body
`memberDepartRestriction`	body
`memberJoinRestriction`	body
`members`	body
`moderatedBy`	body
`moderationEnabled`	body
`notes`	body
`organizationalUnit`	body
`primarySmtpAddress`	body
`requireSenderAuthenticationEnabled`	body
`roomList`	body	boolean (switch)
`samAccountName`	body
`sendModerationNotifications`	body
`type`	body
`dryRun`	query	bool (switch)

Create a mail-enabled security group (MESG)

Creates a mail-enabled security group by passing “type”: “Security” to New-DistributionGroup (the same endpoint as a distribution list). The result has RecipientTypeDetails = MailUniversalSecurityGroup and GroupType containing SecurityEnabled - those are the authoritative discriminators (IsSecurityGroup is a legacy field EXO leaves null in the cloud). Returns 201 + Location.

POST /exchange/v1.0/distributionGroups HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "contoso-security-team",
  "displayName": "Contoso Security Team",
  "type": "Security"
}

HTTP/1.1 201 Created
Location: /exchange/v1.0/distributionGroups/contoso-security-team

{
  "@odata.context": "https://api.contoso.com/exchange/v1.0/$metadata#distributionGroups/$entity",
  "Id": "contoso-security-team",
  "Guid": "a1b2c3d4-1111-2222-3333-444444444444",
  "Name": "contoso-security-team",
  "DisplayName": "Contoso Security Team",
  "Alias": "contoso-security-team",
  "Identity": "contoso-security-team",
  "PrimarySmtpAddress": "contoso-security-team@contoso.com",
  "RecipientType": "MailUniversalSecurityGroup",
  "RecipientTypeDetails": "MailUniversalSecurityGroup",
  "GroupType": "Universal, SecurityEnabled",
  "IsSecurityGroup": null,
  "IsDirSynced": false,
  "ManagedBy": [],
  "MemberJoinRestriction": "Closed",
  "MemberDepartRestriction": "Open"
}

Notes: Live-verified full MESG cycle 2026-05-29 (sanitized): create type:Security -> 201 (RecipientTypeDetails=MailUniversalSecurityGroup, GroupType=‘Universal, SecurityEnabled’) -> polymorphic dispatch on /recipients returns @odata.type #ExchangeApi.MailUniversalSecurityGroup -> delete. IMPORTANT: managing MESG membership/deletion requires the caller to be a group manager - non-manager (incl. app-only) principals get 403 unless ?bypassSecurityGroupManagerCheck=true is passed (see members-add-mesg-bypass.example.json).

Empty body → 400 canonical envelope

An empty body (or body missing required fields like name) returns 400 with the canonical envelope. error.details[] enumerates every missing field by name so callers can fix all in one round-trip.

POST /exchange/v1.0/distributionGroups HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{}

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "BadRequest",
    "message": "Request body failed validation.",
    "target": "body",
    "details": [
      {
        "code": "InvalidProperty",
        "target": "Name",
        "message": "'Name' is required."
      }
    ]
  },
  "correlationId": "0HNLQ76F1QNJ5:00000001"
}

Create a distribution group

Creates a standard mail-enabled distribution list via New-DistributionGroup. Body keys map 1:1 to cmdlet parameters (camelCased). Returns 201 + Location header pointing at the new DG; the body is the freshly-fetched entity.

POST /exchange/v1.0/distributionGroups HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "engineering",
  "primarySmtpAddress": "engineering@contoso.com",
  "alias": "engineering"
}

HTTP/1.1 201 Created
Location: /exchange/v1.0/distributionGroups/engineering

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#distributionGroups/$entity",
  "Id": "engineering",
  "ExchangeGuid": "00000000-0000-0000-0000-000000000000",
  "Guid": "40aae63e-9fdc-484d-9ccd-2a20fa6cdfbe",
  "DisplayName": "engineering",
  "SimpleDisplayName": "",
  "PhoneticDisplayName": null,
  "Name": "engineering",
  "Alias": "engineering",
  "DistinguishedName": "CN=engineering,OU=contoso.com,OU=Microsoft Exchange Hosted Organizations,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
  "Identity": "engineering",
  "ExternalDirectoryObjectId": "bfae6b78-4832-4720-a7b8-c5827b7119f0",
  "PrimarySmtpAddress": "engineering@contoso.com",
  "WindowsLiveID": null,
  "WindowsEmailAddress": "engineering@contoso.com",
  "EmailAddresses": [
    "SMTP:engineering@contoso.com"
  ],
  "EmailAddressPolicyEnabled": false,
  "RecipientType": "MailUniversalDistributionGroup",
  "RecipientTypeDetails": "MailUniversalDistributionGroup",
  "OrganizationalUnit": "eurpr01a017.prod.outlook.com/Microsoft Exchange Hosted Organizations/contoso.com",
  "OrganizationId": "EURPR01A017.PROD.OUTLOOK.COM/Microsoft Exchange Hosted Organizations/contoso.com - EURPR01A017.PROD.OUTLOOK.COM/ConfigurationUnits/contoso.com/Configuration",
  "CustomAttribute1": "",
  "CustomAttribute2": "",
  "CustomAttribute3": "",
  "CustomAttribute4": "",
  "CustomAttribute5": "",
  "ExtensionCustomAttribute1": [],
  "ExtensionCustomAttribute2": [],
  "ExtensionCustomAttribute3": [],
  "ExtensionCustomAttribute4": [],
  "ExtensionCustomAttribute5": [],
  "HiddenFromAddressListsEnabled": false,
  "AddressBookPolicy": null,
  "WhenCreated": "2026-05-25T11:42:59+03:00",
  "WhenChanged": "2026-05-25T11:42:59+03:00",
  "WhenCreatedUTC": "2026-05-25T08:42:59Z",
  "WhenChangedUTC": "2026-05-25T08:42:59Z",
  "GroupType": "Universal",
  "RequireSenderAuthenticationEnabled": true,
  "ReportToManagerEnabled": false,
  "ReportToOriginatorEnabled": true,
  "SendOofMessageToOriginatorEnabled": false,
  "AcceptMessagesOnlyFrom": [],
  "AcceptMessagesOnlyFromDLMembers": [],
  "AcceptMessagesOnlyFromSendersOrMembers": [],
  "RejectMessagesFrom": [],
  "RejectMessagesFromDLMembers": [],
  "RejectMessagesFromSendersOrMembers": [],
  "BypassModerationFromSendersOrMembers": [],
  "ModerationEnabled": false,
  "ModeratedBy": [],
  "SendModerationNotifications": "Always",
  "ManagedBy": [],
  "Members_Raw": [],
  "MailTip": null,
  "MailTipTranslations": [],
  "GrantSendOnBehalfTo": [],
  "IsDirSynced": false,
  "IsSecurityGroup": false,
  "MemberJoinRestriction": "Closed",
  "MemberDepartRestriction": "Open",
  "BypassNestedModerationEnabled": false,
  "SendOofMessageToOriginatorEnabled_DL": null,
  "ExpansionServer": "",
  "UMDtmfMap": [],
  "RoomList": [],
  "RoomMailboxAccountEnabled": null,
  "MaxReceiveSize": "Unlimited",
  "MaxSendSize": "Unlimited",
  "ResourceCustom": [],
  "Description": null,
  "Notes": null,
  "OperatorNumber": null,
  "PhoneticDisplayName_DL": null,
  "RecipientContainerHint": null,
  "HiddenGroupMembershipEnabled": false,
  "AcceptMessagesOnlyFromDLMembersWithDisplayNames": [],
  "AcceptMessagesOnlyFromSendersOrMembersWithDisplayNames": [],
  "AcceptMessagesOnlyFromWithDisplayNames": [],
  "AddressListMembership": [
    "\\Default Global Address List",
    "\\Offline Global Address List",
    "\\All Distribution Lists",
    "\\Groups(VLV)",
    "\\All Groups(VLV)",
    "\\All Recipients(VLV)"
  ],
  "AdministrativeUnits": [],
  "ArbitrationMailbox": "TenantSetting_AC9A8876-0461-47EA-9d4C-FE8D02AEF7D5",
  "BccBlocked": false,
  "BypassModerationFromSendersOrMembersWithDisplayNames": [],
  "CustomAttribute10": "",
  "CustomAttribute11": "",
  "CustomAttribute12": "",
  "CustomAttribute13": "",
  "CustomAttribute14": "",
  "CustomAttribute15": "",
  "CustomAttribute6": "",
  "CustomAttribute7": "",
  "CustomAttribute8": "",
  "CustomAttribute9": "",
  "ExchangeObjectId": "40aae63e-9fdc-484d-9ccd-2a20fa6cdfbe",
  "GrantSendOnBehalfToWithDisplayNames": [],
  "LastExchangeChangedTime": null,
  "LegacyExchangeDN": "/o=ExchangeLabs/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/cn=Recipients/cn=cef01251811b409a84d601ef888826bd-phase5-exam",
  "ManagedByWithDisplayName": [],
  "MigrationToUnifiedGroupInProgress": false,
  "ModeratedByWithDisplayNames": [],
  "OrganizationalUnitRoot": "contoso.com",
  "PoliciesExcluded": [
    "{26491cfc-9e50-4857-861b-0cb8df22b5d7}"
  ],
  "PoliciesIncluded": [],
  "RejectMessagesFromSendersOrMembersWithDisplayNames": [],
  "SamAccountName": "$SH4FI0-MD36QDG7GUQJ"
}

Notes: MESG variants pass "type": "Security" in the body (see create-mesg-security.example.json once authored).

GET /exchange/v1.0/distributionGroups/eligibleForUpgrade

GET /distributionGroups/eligibleForUpgrade - DGs eligible for M365 upgrade. Optional filters: ?identity=…, ?managedBy=….

Backing cmdlet: Get-EligibleDistributionGroupForMigration. Role: Group.Read (Community).

Parameter	In	Type	Description
`identity`	query	string
`managedBy`	query	string
`all`	query	bool (switch)	Return all results instead of the EXO default of 1000. Maps -ResultSize Unlimited on Get-EligibleDistributionGroupForMigration; prevents silent truncation in large tenants.

List distribution groups eligible for Microsoft 365 group upgrade

Sub-resource of the distribution groups collection at GET /distributionGroups - returns the distribution lists that can be upgraded to Microsoft 365 (unified) groups, backed by Get-EligibleDistributionGroupForMigration.

GET /exchange/v1.0/distributionGroups/eligibleForUpgrade HTTP/1.1
Authorization: Bearer {token}

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#distributionGroups",
  "value": [
    {
      "Id": "DL Contoso E3 Users20260223161420",
      "ExchangeGuid": "00000000-0000-0000-0000-000000000000",
      "Guid": null,
      "DisplayName": "DL Contoso E3 Users",
      "SimpleDisplayName": null,
      "PhoneticDisplayName": null,
      "Name": null,
      "Alias": null,
      "DistinguishedName": null,
      "Identity": null,
      "ExternalDirectoryObjectId": "c0f95716-ca55-4763-bd78-fd05671400eb",
      "PrimarySmtpAddress": "DLContosoE3Users@contoso.com",
      "WindowsLiveID": null,
      "WindowsEmailAddress": null,
      "EmailAddresses": [],
      "EmailAddressPolicyEnabled": false,
      "RecipientType": null,
      "RecipientTypeDetails": null,
      "OrganizationalUnit": null,
      "OrganizationId": null,
      "CustomAttribute1": null,
      "CustomAttribute2": null,
      "CustomAttribute3": null,
      "CustomAttribute4": null,
      "CustomAttribute5": null,
      "ExtensionCustomAttribute1": [],
      "ExtensionCustomAttribute2": [],
      "ExtensionCustomAttribute3": [],
      "ExtensionCustomAttribute4": [],
      "ExtensionCustomAttribute5": [],
      "HiddenFromAddressListsEnabled": false,
      "AddressBookPolicy": null,
      "WhenCreated": "2026-03-31T17:52:40+03:00",
      "WhenChanged": "2026-05-22T03:22:37+03:00",
      "WhenCreatedUTC": null,
      "WhenChangedUTC": null,
      "GroupType": null,
      "RequireSenderAuthenticationEnabled": false,
      "ReportToManagerEnabled": false,
      "ReportToOriginatorEnabled": false,
      "SendOofMessageToOriginatorEnabled": false,
      "AcceptMessagesOnlyFrom": [],
      "AcceptMessagesOnlyFromDLMembers": [],
      "AcceptMessagesOnlyFromSendersOrMembers": [],
      "RejectMessagesFrom": [],
      "RejectMessagesFromDLMembers": [],
      "RejectMessagesFromSendersOrMembers": [],
      "BypassModerationFromSendersOrMembers": [],
      "ModerationEnabled": false,
      "ModeratedBy": [],
      "SendModerationNotifications": null,
      "ManagedBy": [],
      "Members_Raw": [],
      "MailTip": null,
      "MailTipTranslations": [],
      "GrantSendOnBehalfTo": [],
      "IsDirSynced": false,
      "IsSecurityGroup": false,
      "MemberJoinRestriction": null,
      "MemberDepartRestriction": null,
      "BypassNestedModerationEnabled": null,
      "SendOofMessageToOriginatorEnabled_DL": null,
      "ExpansionServer": null,
      "UMDtmfMap": [],
      "RoomList": [],
      "RoomMailboxAccountEnabled": null,
      "MaxReceiveSize": null,
      "MaxSendSize": null,
      "ResourceCustom": [],
      "Description": null,
      "Notes": null,
      "OperatorNumber": null,
      "PhoneticDisplayName_DL": null,
      "RecipientContainerHint": null,
      "HiddenGroupMembershipEnabled": null,
      "AcceptMessagesOnlyFromDLMembersWithDisplayNames": [],
      "AcceptMessagesOnlyFromSendersOrMembersWithDisplayNames": [],
      "AcceptMessagesOnlyFromWithDisplayNames": [],
      "AddressListMembership": [],
      "AdministrativeUnits": [],
      "ArbitrationMailbox": null,
      "BccBlocked": false,
      "BypassModerationFromSendersOrMembersWithDisplayNames": [],
      "CustomAttribute10": null,
      "CustomAttribute11": null,
      "CustomAttribute12": null,
      "CustomAttribute13": null,
      "CustomAttribute14": null,
      "CustomAttribute15": null,
      "CustomAttribute6": null,
      "CustomAttribute7": null,
      "CustomAttribute8": null,
      "CustomAttribute9": null,
      "ExchangeObjectId": null,
      "GrantSendOnBehalfToWithDisplayNames": [],
      "LastExchangeChangedTime": null,
      "LegacyExchangeDN": "/o=ExchangeLabs/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/cn=Recipients/cn=6bb195e7d4f64998a0bf45e383728ee0-DL Contoso",
      "ManagedByWithDisplayName": [],
      "MigrationToUnifiedGroupInProgress": false,
      "ModeratedByWithDisplayNames": [],
      "OrganizationalUnitRoot": null,
      "PoliciesExcluded": [],
      "PoliciesIncluded": [],
      "RejectMessagesFromSendersOrMembersWithDisplayNames": [],
      "SamAccountName": null
    },
    {
      "Id": "DL Contoso Users20260223144339",
      "ExchangeGuid": "00000000-0000-0000-0000-000000000000",
      "Guid": null,
      "DisplayName": "DL Contoso Users",
      "SimpleDisplayName": null,
      "PhoneticDisplayName": null,
      "Name": null,
      "Alias": null,
      "DistinguishedName": null,
      "Identity": null,
      "ExternalDirectoryObjectId": "d3f83ec5-a973-4b26-925c-b2165230f03f",
      "PrimarySmtpAddress": "DLContosoUsers@contoso.com",
      "WindowsLiveID": null,
      "WindowsEmailAddress": null,
      "EmailAddresses": [],
      "EmailAddressPolicyEnabled": false,
      "RecipientType": null,
      "RecipientTypeDetails": null,
      "OrganizationalUnit": null,
      "OrganizationId": null,
      "CustomAttribute1": null,
      "CustomAttribute2": null,
      "CustomAttribute3": null,
      "CustomAttribute4": null,
      "CustomAttribute5": null,
      "ExtensionCustomAttribute1": [],
      "ExtensionCustomAttribute2": [],
      "ExtensionCustomAttribute3": [],
      "ExtensionCustomAttribute4": [],
      "ExtensionCustomAttribute5": [],
      "HiddenFromAddressListsEnabled": false,
      "AddressBookPolicy": null,
      "WhenCreated": "2026-03-31T17:52:37+03:00",
      "WhenChanged": "2026-03-31T17:54:47+03:00",
      "WhenCreatedUTC": null,
      "WhenChangedUTC": null,
      "GroupType": null,
      "RequireSenderAuthenticationEnabled": false,
      "ReportToManagerEnabled": false,
      "ReportToOriginatorEnabled": false,
      "SendOofMessageToOriginatorEnabled": false,
      "AcceptMessagesOnlyFrom": [],
      "AcceptMessagesOnlyFromDLMembers": [],
      "AcceptMessagesOnlyFromSendersOrMembers": [],
      "RejectMessagesFrom": [],
      "RejectMessagesFromDLMembers": [],
      "RejectMessagesFromSendersOrMembers": [],
      "BypassModerationFromSendersOrMembers": [],
      "ModerationEnabled": false,
      "ModeratedBy": [],
      "SendModerationNotifications": null,
      "ManagedBy": [],
      "Members_Raw": [],
      "MailTip": null,
      "MailTipTranslations": [],
      "GrantSendOnBehalfTo": [],
      "IsDirSynced": false,
      "IsSecurityGroup": false,
      "MemberJoinRestriction": null,
      "MemberDepartRestriction": null,
      "BypassNestedModerationEnabled": null,
      "SendOofMessageToOriginatorEnabled_DL": null,
      "ExpansionServer": null,
      "UMDtmfMap": [],
      "RoomList": [],
      "RoomMailboxAccountEnabled": null,
      "MaxReceiveSize": null,
      "MaxSendSize": null,
      "ResourceCustom": [],
      "Description": null,
      "Notes": null,
      "OperatorNumber": null,
      "PhoneticDisplayName_DL": null,
      "RecipientContainerHint": null,
      "HiddenGroupMembershipEnabled": null,
      "AcceptMessagesOnlyFromDLMembersWithDisplayNames": [],
      "AcceptMessagesOnlyFromSendersOrMembersWithDisplayNames": [],
      "AcceptMessagesOnlyFromWithDisplayNames": [],
      "AddressListMembership": [],
      "AdministrativeUnits": [],
      "ArbitrationMailbox": null,
      "BccBlocked": false,
      "BypassModerationFromSendersOrMembersWithDisplayNames": [],
      "CustomAttribute10": null,
      "CustomAttribute11": null,
      "CustomAttribute12": null,
      "CustomAttribute13": null,
      "CustomAttribute14": null,
      "CustomAttribute15": null,
      "CustomAttribute6": null,
      "CustomAttribute7": null,
      "CustomAttribute8": null,
      "CustomAttribute9": null,
      "ExchangeObjectId": null,
      "GrantSendOnBehalfToWithDisplayNames": [],
      "LastExchangeChangedTime": null,
      "LegacyExchangeDN": "/o=ExchangeLabs/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/cn=Recipients/cn=d6ff42fb3d2a46f392d5d28fe5a53557-DL Contoso",
      "ManagedByWithDisplayName": [],
      "MigrationToUnifiedGroupInProgress": false,
      "ModeratedByWithDisplayNames": [],
      "OrganizationalUnitRoot": null,
      "PoliciesExcluded": [],
      "PoliciesIncluded": [],
      "RejectMessagesFromSendersOrMembersWithDisplayNames": [],
      "SamAccountName": null
    },
    {
      "Id": "DL Contoso RO Testing 123",
      "ExchangeGuid": "00000000-0000-0000-0000-000000000000",
      "Guid": null,
      "DisplayName": "DL Contoso RO Testing 123",
      "SimpleDisplayName": null,
      "PhoneticDisplayName": null,
      "Name": null,
      "Alias": null,
      "DistinguishedName": null,
      "Identity": null,
      "ExternalDirectoryObjectId": "da51639c-6449-47ac-a678-42f431b4213e",
      "PrimarySmtpAddress": "DLContosoROTesting123@contoso.com",
      "WindowsLiveID": null,
      "WindowsEmailAddress": null,
      "EmailAddresses": [],
      "EmailAddressPolicyEnabled": false,
      "RecipientType": null,
      "RecipientTypeDetails": null,
      "OrganizationalUnit": null,
      "OrganizationId": null,
      "CustomAttribute1": null,
      "CustomAttribute2": null,
      "CustomAttribute3": null,
      "CustomAttribute4": null,
      "CustomAttribute5": null,
      "ExtensionCustomAttribute1": [],
      "ExtensionCustomAttribute2": [],
      "ExtensionCustomAttribute3": [],
      "ExtensionCustomAttribute4": [],
      "ExtensionCustomAttribute5": [],
      "HiddenFromAddressListsEnabled": false,
      "AddressBookPolicy": null,
      "WhenCreated": "2026-05-28T18:56:32+03:00",
      "WhenChanged": "2026-05-28T20:48:40+03:00",
      "WhenCreatedUTC": null,
      "WhenChangedUTC": null,
      "GroupType": null,
      "RequireSenderAuthenticationEnabled": false,
      "ReportToManagerEnabled": false,
      "ReportToOriginatorEnabled": false,
      "SendOofMessageToOriginatorEnabled": false,
      "AcceptMessagesOnlyFrom": [],
      "AcceptMessagesOnlyFromDLMembers": [],
      "AcceptMessagesOnlyFromSendersOrMembers": [],
      "RejectMessagesFrom": [],
      "RejectMessagesFromDLMembers": [],
      "RejectMessagesFromSendersOrMembers": [],
      "BypassModerationFromSendersOrMembers": [],
      "ModerationEnabled": false,
      "ModeratedBy": [],
      "SendModerationNotifications": null,
      "ManagedBy": [],
      "Members_Raw": [],
      "MailTip": null,
      "MailTipTranslations": [],
      "GrantSendOnBehalfTo": [],
      "IsDirSynced": false,
      "IsSecurityGroup": false,
      "MemberJoinRestriction": null,
      "MemberDepartRestriction": null,
      "BypassNestedModerationEnabled": null,
      "SendOofMessageToOriginatorEnabled_DL": null,
      "ExpansionServer": null,
      "UMDtmfMap": [],
      "RoomList": [],
      "RoomMailboxAccountEnabled": null,
      "MaxReceiveSize": null,
      "MaxSendSize": null,
      "ResourceCustom": [],
      "Description": null,
      "Notes": null,
      "OperatorNumber": null,
      "PhoneticDisplayName_DL": null,
      "RecipientContainerHint": null,
      "HiddenGroupMembershipEnabled": null,
      "AcceptMessagesOnlyFromDLMembersWithDisplayNames": [],
      "AcceptMessagesOnlyFromSendersOrMembersWithDisplayNames": [],
      "AcceptMessagesOnlyFromWithDisplayNames": [],
      "AddressListMembership": [],
      "AdministrativeUnits": [],
      "ArbitrationMailbox": null,
      "BccBlocked": false,
      "BypassModerationFromSendersOrMembersWithDisplayNames": [],
      "CustomAttribute10": null,
      "CustomAttribute11": null,
      "CustomAttribute12": null,
      "CustomAttribute13": null,
      "CustomAttribute14": null,
      "CustomAttribute15": null,
      "CustomAttribute6": null,
      "CustomAttribute7": null,
      "CustomAttribute8": null,
      "CustomAttribute9": null,
      "ExchangeObjectId": null,
      "GrantSendOnBehalfToWithDisplayNames": [],
      "LastExchangeChangedTime": null,
      "LegacyExchangeDN": "/o=ExchangeLabs/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/cn=Recipients/cn=032ca6d179504e7c9f60fb0dc76a2b6b-DL Contoso",
      "ManagedByWithDisplayName": [],
      "MigrationToUnifiedGroupInProgress": false,
      "ModeratedByWithDisplayNames": [],
      "OrganizationalUnitRoot": null,
      "PoliciesExcluded": [],
      "PoliciesIncluded": [],
      "RejectMessagesFromSendersOrMembersWithDisplayNames": [],
      "SamAccountName": null
    }
  ]
}

GET /exchange/v1.0/distributionGroups/{key}

Get a single distributionGroups entry by Identity.

Backing cmdlet: Get-DistributionGroup. Role: Group.Read (Community).

Get a single distribution group

Returns one DL/MESG by Id, Alias, or PrimarySmtpAddress. Includes the ManagedBy (owners), member-restrictions, moderation config, and Exchange-side directory state.

GET /exchange/v1.0/distributionGroups/{key} HTTP/1.1
Authorization: Bearer {token}

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#distributionGroups/$entity",
  "Id": "197c9ca8-ce81-41d4-97e2-2a06878298a8",
  "ExchangeGuid": "00000000-0000-0000-0000-000000000000",
  "Guid": "dd5fcb6e-1d6b-46b3-9814-9aecb2029783",
  "DisplayName": "Sales Team",
  "SimpleDisplayName": "",
  "PhoneticDisplayName": null,
  "Name": "197c9ca8-ce81-41d4-97e2-2a06878298a8",
  "Alias": "sales-team",
  "DistinguishedName": "CN=197c9ca8-ce81-41d4-97e2-2a06878298a8,OU=contoso.com,OU=Microsoft Exchange Hosted Organizations,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
  "Identity": "197c9ca8-ce81-41d4-97e2-2a06878298a8",
  "ExternalDirectoryObjectId": "197c9ca8-ce81-41d4-97e2-2a06878298a8",
  "PrimarySmtpAddress": "sales-team@contoso.com",
  "WindowsLiveID": null,
  "WindowsEmailAddress": "sales-team@contoso.com",
  "EmailAddresses": [
    "smtp:sales-team@contoso.com",
    "SMTP:sales-team@contoso.com"
  ],
  "EmailAddressPolicyEnabled": false,
  "RecipientType": "MailUniversalDistributionGroup",
  "RecipientTypeDetails": "MailUniversalDistributionGroup",
  "OrganizationalUnit": "eurpr01a017.prod.outlook.com/Microsoft Exchange Hosted Organizations/contoso.com",
  "OrganizationId": "EURPR01A017.PROD.OUTLOOK.COM/Microsoft Exchange Hosted Organizations/contoso.com - EURPR01A017.PROD.OUTLOOK.COM/ConfigurationUnits/contoso.com/Configuration",
  "CustomAttribute1": "",
  "CustomAttribute2": "",
  "CustomAttribute3": "",
  "CustomAttribute4": "",
  "CustomAttribute5": "",
  "ExtensionCustomAttribute1": [],
  "ExtensionCustomAttribute2": [],
  "ExtensionCustomAttribute3": [],
  "ExtensionCustomAttribute4": [],
  "ExtensionCustomAttribute5": [],
  "HiddenFromAddressListsEnabled": false,
  "AddressBookPolicy": null,
  "WhenCreated": "2026-03-30T17:47:41+03:00",
  "WhenChanged": "2026-03-30T17:50:25+03:00",
  "WhenCreatedUTC": "2026-03-30T14:47:41Z",
  "WhenChangedUTC": "2026-03-30T14:50:25Z",
  "GroupType": "Universal",
  "RequireSenderAuthenticationEnabled": false,
  "ReportToManagerEnabled": false,
  "ReportToOriginatorEnabled": false,
  "SendOofMessageToOriginatorEnabled": false,
  "AcceptMessagesOnlyFrom": [],
  "AcceptMessagesOnlyFromDLMembers": [],
  "AcceptMessagesOnlyFromSendersOrMembers": [],
  "RejectMessagesFrom": [],
  "RejectMessagesFromDLMembers": [],
  "RejectMessagesFromSendersOrMembers": [],
  "BypassModerationFromSendersOrMembers": [],
  "ModerationEnabled": false,
  "ModeratedBy": [],
  "SendModerationNotifications": "Always",
  "ManagedBy": [],
  "Members_Raw": [],
  "MailTip": null,
  "MailTipTranslations": [],
  "GrantSendOnBehalfTo": [],
  "IsDirSynced": true,
  "IsSecurityGroup": false,
  "MemberJoinRestriction": "Closed",
  "MemberDepartRestriction": "Closed",
  "BypassNestedModerationEnabled": false,
  "SendOofMessageToOriginatorEnabled_DL": null,
  "ExpansionServer": "",
  "UMDtmfMap": [],
  "RoomList": [],
  "RoomMailboxAccountEnabled": null,
  "MaxReceiveSize": "Unlimited",
  "MaxSendSize": "Unlimited",
  "ResourceCustom": [],
  "Description": null,
  "Notes": null,
  "OperatorNumber": null,
  "PhoneticDisplayName_DL": null,
  "RecipientContainerHint": null,
  "HiddenGroupMembershipEnabled": false,
  "AcceptMessagesOnlyFromDLMembersWithDisplayNames": [],
  "AcceptMessagesOnlyFromSendersOrMembersWithDisplayNames": [],
  "AcceptMessagesOnlyFromWithDisplayNames": [],
  "AddressListMembership": [
    "\\Default Global Address List",
    "\\All Recipients(VLV)",
    "\\All Groups(VLV)",
    "\\Groups(VLV)",
    "\\Offline Global Address List",
    "\\All Distribution Lists"
  ],
  "AdministrativeUnits": [],
  "ArbitrationMailbox": "TenantSetting_AC9A8876-0461-47EA-9d4C-FE8D02AEF7D5",
  "BccBlocked": false,
  "BypassModerationFromSendersOrMembersWithDisplayNames": [],
  "CustomAttribute10": "",
  "CustomAttribute11": "",
  "CustomAttribute12": "",
  "CustomAttribute13": "",
  "CustomAttribute14": "",
  "CustomAttribute15": "",
  "CustomAttribute6": "",
  "CustomAttribute7": "",
  "CustomAttribute8": "",
  "CustomAttribute9": "",
  "ExchangeObjectId": "5e21f7f7-f83c-496f-a0ef-a5d0aa520818",
  "GrantSendOnBehalfToWithDisplayNames": [],
  "LastExchangeChangedTime": null,
  "LegacyExchangeDN": "/o=ExchangeLabs/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/cn=Recipients/cn=11aa342d61464e659e050a22aaefab30-197c9ca8-ce",
  "ManagedByWithDisplayName": [],
  "MigrationToUnifiedGroupInProgress": false,
  "ModeratedByWithDisplayNames": [],
  "OrganizationalUnitRoot": "contoso.com",
  "PoliciesExcluded": [
    "{26491cfc-9e50-4857-861b-0cb8df22b5d7}"
  ],
  "PoliciesIncluded": [],
  "RejectMessagesFromSendersOrMembersWithDisplayNames": [],
  "SamAccountName": "$9O8HG0-MTDQKGHEE9SS"
}

PATCH /exchange/v1.0/distributionGroups/{key}

PATCH /distributionGroups/{key} - partial update via Set-DistributionGroup. Cmdlet-behavior flags surfaced as query params (BypassSecurityGroupManagerCheck, IgnoreDefaultScope, IgnoreNamingPolicy, ForceUpgrade, ResetMigrationToUnifiedGroup, UpdateMemberCount). Returns 200 + the updated entity.

Backing cmdlet: Set-DistributionGroup. Role: Group.ReadWrite (Pro).

Parameter	In	Type
`acceptMessagesOnlyFrom`	body
`acceptMessagesOnlyFromDLMembers`	body
`acceptMessagesOnlyFromSendersOrMembers`	body
`alias`	body
`arbitrationMailbox`	body
`bccBlocked`	body
`bypassModerationFromSendersOrMembers`	body
`bypassNestedModerationEnabled`	body
`createDTMFMap`	body
`customAttribute1`	body
`customAttribute10`	body
`customAttribute11`	body
`customAttribute12`	body
`customAttribute13`	body
`customAttribute14`	body
`customAttribute15`	body
`customAttribute2`	body
`customAttribute3`	body
`customAttribute4`	body
`customAttribute5`	body
`customAttribute6`	body
`customAttribute7`	body
`customAttribute8`	body
`customAttribute9`	body
`description`	body
`displayName`	body
`emailAddresses`	body
`emailAddressPolicyEnabled`	body
`expansionServer`	body
`extensionCustomAttribute1`	body
`extensionCustomAttribute2`	body
`extensionCustomAttribute3`	body
`extensionCustomAttribute4`	body
`extensionCustomAttribute5`	body
`grantSendOnBehalfTo`	body
`hiddenFromAddressListsEnabled`	body
`hiddenGroupMembershipEnabled`	body	boolean (switch)
`mailTip`	body
`mailTipTranslations`	body
`managedBy`	body
`maxReceiveSize`	body
`maxSendSize`	body
`memberDepartRestriction`	body
`memberJoinRestriction`	body
`moderatedBy`	body
`moderationEnabled`	body
`name`	body
`primarySmtpAddress`	body
`rejectMessagesFrom`	body
`rejectMessagesFromDLMembers`	body
`rejectMessagesFromSendersOrMembers`	body
`reportToManagerEnabled`	body
`reportToOriginatorEnabled`	body
`requireSenderAuthenticationEnabled`	body
`roomList`	body	boolean (switch)
`samAccountName`	body
`sendModerationNotifications`	body
`sendOofMessageToOriginatorEnabled`	body
`simpleDisplayName`	body
`umDtmfMap`	body
`windowsEmailAddress`	body
`bypassSecurityGroupManagerCheck`	query	bool (switch)
`ignoreDefaultScope`	query	bool (switch)
`ignoreNamingPolicy`	query	bool (switch)
`forceUpgrade`	query	bool (switch)
`resetMigrationToUnifiedGroup`	query	bool (switch)
`updateMemberCount`	query	bool (switch)
`dryRun`	query	bool (switch)

PATCH displayName on an existing DG

Partial update via Set-DistributionGroup. Only fields present in the body are passed to the cmdlet. URL {key} becomes -Identity. Returns 200 with the freshly-fetched entity (post-Set state).

PATCH /exchange/v1.0/distributionGroups/{key} HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "displayName": "Engineering (Renamed)"
}

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#distributionGroups/$entity",
  "Id": "engineering",
  "ExchangeGuid": "00000000-0000-0000-0000-000000000000",
  "Guid": "40aae63e-9fdc-484d-9ccd-2a20fa6cdfbe",
  "DisplayName": "Phase 5 Example DG (renamed)",
  "SimpleDisplayName": "",
  "PhoneticDisplayName": null,
  "Name": "engineering",
  "Alias": "engineering",
  "DistinguishedName": "CN=engineering,OU=contoso.com,OU=Microsoft Exchange Hosted Organizations,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
  "Identity": "engineering",
  "ExternalDirectoryObjectId": "bfae6b78-4832-4720-a7b8-c5827b7119f0",
  "PrimarySmtpAddress": "engineering@contoso.com",
  "WindowsLiveID": null,
  "WindowsEmailAddress": "engineering@contoso.com",
  "EmailAddresses": [
    "SMTP:engineering@contoso.com"
  ],
  "EmailAddressPolicyEnabled": false,
  "RecipientType": "MailUniversalDistributionGroup",
  "RecipientTypeDetails": "MailUniversalDistributionGroup",
  "OrganizationalUnit": "eurpr01a017.prod.outlook.com/Microsoft Exchange Hosted Organizations/contoso.com",
  "OrganizationId": "EURPR01A017.PROD.OUTLOOK.COM/Microsoft Exchange Hosted Organizations/contoso.com - EURPR01A017.PROD.OUTLOOK.COM/ConfigurationUnits/contoso.com/Configuration",
  "CustomAttribute1": "",
  "CustomAttribute2": "",
  "CustomAttribute3": "",
  "CustomAttribute4": "",
  "CustomAttribute5": "",
  "ExtensionCustomAttribute1": [],
  "ExtensionCustomAttribute2": [],
  "ExtensionCustomAttribute3": [],
  "ExtensionCustomAttribute4": [],
  "ExtensionCustomAttribute5": [],
  "HiddenFromAddressListsEnabled": false,
  "AddressBookPolicy": null,
  "WhenCreated": "2026-05-25T11:42:59+03:00",
  "WhenChanged": "2026-05-25T11:43:02+03:00",
  "WhenCreatedUTC": "2026-05-25T08:42:59Z",
  "WhenChangedUTC": "2026-05-25T08:43:02Z",
  "GroupType": "Universal",
  "RequireSenderAuthenticationEnabled": true,
  "ReportToManagerEnabled": false,
  "ReportToOriginatorEnabled": true,
  "SendOofMessageToOriginatorEnabled": false,
  "AcceptMessagesOnlyFrom": [],
  "AcceptMessagesOnlyFromDLMembers": [],
  "AcceptMessagesOnlyFromSendersOrMembers": [],
  "RejectMessagesFrom": [],
  "RejectMessagesFromDLMembers": [],
  "RejectMessagesFromSendersOrMembers": [],
  "BypassModerationFromSendersOrMembers": [],
  "ModerationEnabled": false,
  "ModeratedBy": [],
  "SendModerationNotifications": "Always",
  "ManagedBy": [],
  "Members_Raw": [],
  "MailTip": null,
  "MailTipTranslations": [],
  "GrantSendOnBehalfTo": [],
  "IsDirSynced": false,
  "IsSecurityGroup": false,
  "MemberJoinRestriction": "Closed",
  "MemberDepartRestriction": "Open",
  "BypassNestedModerationEnabled": false,
  "SendOofMessageToOriginatorEnabled_DL": null,
  "ExpansionServer": "",
  "UMDtmfMap": [],
  "RoomList": [],
  "RoomMailboxAccountEnabled": null,
  "MaxReceiveSize": "Unlimited",
  "MaxSendSize": "Unlimited",
  "ResourceCustom": [],
  "Description": null,
  "Notes": null,
  "OperatorNumber": null,
  "PhoneticDisplayName_DL": null,
  "RecipientContainerHint": null,
  "HiddenGroupMembershipEnabled": false,
  "AcceptMessagesOnlyFromDLMembersWithDisplayNames": [],
  "AcceptMessagesOnlyFromSendersOrMembersWithDisplayNames": [],
  "AcceptMessagesOnlyFromWithDisplayNames": [],
  "AddressListMembership": [
    "\\Default Global Address List",
    "\\Offline Global Address List",
    "\\All Distribution Lists",
    "\\Groups(VLV)",
    "\\All Groups(VLV)",
    "\\All Recipients(VLV)"
  ],
  "AdministrativeUnits": [],
  "ArbitrationMailbox": "TenantSetting_AC9A8876-0461-47EA-9d4C-FE8D02AEF7D5",
  "BccBlocked": false,
  "BypassModerationFromSendersOrMembersWithDisplayNames": [],
  "CustomAttribute10": "",
  "CustomAttribute11": "",
  "CustomAttribute12": "",
  "CustomAttribute13": "",
  "CustomAttribute14": "",
  "CustomAttribute15": "",
  "CustomAttribute6": "",
  "CustomAttribute7": "",
  "CustomAttribute8": "",
  "CustomAttribute9": "",
  "ExchangeObjectId": "40aae63e-9fdc-484d-9ccd-2a20fa6cdfbe",
  "GrantSendOnBehalfToWithDisplayNames": [],
  "LastExchangeChangedTime": null,
  "LegacyExchangeDN": "/o=ExchangeLabs/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/cn=Recipients/cn=cef01251811b409a84d601ef888826bd-phase5-exam",
  "ManagedByWithDisplayName": [],
  "MigrationToUnifiedGroupInProgress": false,
  "ModeratedByWithDisplayNames": [],
  "OrganizationalUnitRoot": "contoso.com",
  "PoliciesExcluded": [
    "{26491cfc-9e50-4857-861b-0cb8df22b5d7}"
  ],
  "PoliciesIncluded": [],
  "RejectMessagesFromSendersOrMembersWithDisplayNames": [],
  "SamAccountName": "$SH4FI0-MD36QDG7GUQJ"
}

Notes: Rename via name is supported - WriteControllerBase does rename-aware re-fetch (tries the new Name first, falls back to URL key).

DELETE /exchange/v1.0/distributionGroups/{key}

DELETE /distributionGroups/{key} - Remove-DistributionGroup. Use ?bypassSecurityGroupManagerCheck=true for non-owner removal of MESGs.

Backing cmdlet: Remove-DistributionGroup. Role: Group.ReadWrite (Pro).

Parameter	In	Type
`bypassSecurityGroupManagerCheck`	query	bool (switch)
`ignoreDefaultScope`	query	bool (switch)
`dryRun`	query	bool (switch)

Delete a distribution group

Removes the DG via Remove-DistributionGroup. URL {key} is the identity (Id / Alias / PrimarySmtpAddress all work). Returns 204 with no body. Use ?bypassSecurityGroupManagerCheck=true for non-owner removal of MESGs; ?dryRun=true to preview without applying.

DELETE /exchange/v1.0/distributionGroups/{key} HTTP/1.1
Authorization: Bearer {token}

HTTP/1.1 204 No Content

GET /exchange/v1.0/distributionGroups/{key}/members

GET /distributionGroups/{key}/members - polymorphic members via Get-DistributionGroupMember.

Backing cmdlet: Get-DistributionGroupMember. Role: Group.Read (Community).

Parameter	In	Type	Required	Description
`all`	query	bool (switch)		Return all results instead of the EXO default of 1000. Maps -ResultSize Unlimited on Get-DistributionGroupMember; prevents silent truncation in large tenants.
`includeSoftDeletedObjects`	query	bool (switch)		Include soft-deleted members in the results. Maps -IncludeSoftDeletedObjects on Get-DistributionGroupMember.

List members of a distribution group

Sub-resource of the DG at GET /distributionGroups/{key}. Returns the polymorphic member list - each row is a Recipient subtype (Mailbox, MailUser, MailContact, nested DistributionGroup). Use the RecipientTypeDetails discriminator to identify each.

GET /exchange/v1.0/distributionGroups/{key}/members HTTP/1.1
Authorization: Bearer {token}

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#recipients",
  "value": []
}

Notes: PUT /members performs a bulk-replace. POST /members/$ref + DELETE /members/{id}/$ref are the surgical add/remove.

PUT /exchange/v1.0/distributionGroups/{key}/members

PUT /distributionGroups/{key}/members - Update-DistributionGroupMember replaces the FULL member list. Empty {“members”: []} clears membership.

Backing cmdlet: Update-DistributionGroupMember. Role: Group.ReadWrite (Pro).

Parameter	In	Type	Required
`members`	body	array	yes
`bypassSecurityGroupManagerCheck`	query	bool (switch)
`dryRun`	query	bool (switch)

Replace the full membership of a distribution group

Sub-resource of the distribution group at GET /distributionGroups/{key} - replaces the entire member list via Update-DistributionGroupMember. The members array maps to the cmdlet’s -Members parameter; an empty array clears all membership.

PUT /exchange/v1.0/distributionGroups/{key}/members HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "members": [
    "casey.jones@contoso.com",
    "morgan.lee@contoso.com"
  ]
}

HTTP/1.1 204 No Content

Notes: Doc-derived from Wiki + write-param allowlist; not live-captured. Body fields are Wiki-valid; values are illustrative.

POST /exchange/v1.0/distributionGroups/{key}/members/$ref

POST /distributionGroups/{key}/members/$ref - Add-DistributionGroupMember. Returns 204. MESG note: for a mail-enabled SECURITY group, EXO requires the caller to be a group manager (ManagedBy). App-only / non-manager principals get 403 (“This operation can only be performed by a manager of the group”) unless you pass ?bypassSecurityGroupManagerCheck=true.

Backing cmdlet: Add-DistributionGroupMember. Role: Group.ReadWrite (Pro).

Parameter	In	Type	Required
`member`	body	string	yes
`bypassSecurityGroupManagerCheck`	query	bool (switch)
`dryRun`	query	bool (switch)

Add a member to a MESG (security-group-manager bypass)

Sub-resource of GET /distributionGroups/{key}/members. Adds a member via Add-DistributionGroupMember. For a mail-enabled SECURITY group, EXO only lets a group MANAGER modify membership - a non-manager (including an app-only principal) gets 403 (“This operation can only be performed by a manager of the group”). Pass ?bypassSecurityGroupManagerCheck=true to override. Returns 204.

POST /exchange/v1.0/distributionGroups/{key}/members/$ref?bypassSecurityGroupManagerCheck=true HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "member": "john.woods@contoso.com"
}

HTTP/1.1 204 No Content

Notes: Live-verified 2026-05-29 (sanitized): WITHOUT the flag, adding a member to a MESG returned 403 with the EXO envelope ‘This operation can only be performed by a manager of the group’; WITH ?bypassSecurityGroupManagerCheck=true it returned 204. The flag defaults OFF (do not silently bypass a security control). The same flag applies to DELETE member, PUT members, PATCH, and DELETE on a MESG.

Add a member to a distribution group

Sub-resource of GET /distributionGroups/{key}/members. Sub-resource of the distribution group at GET /distributionGroups/{key} - adds a single recipient to the group’s membership via Add-DistributionGroupMember. The body’s member maps 1:1 to the cmdlet’s -Member parameter.

POST /exchange/v1.0/distributionGroups/{key}/members/$ref HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "member": "casey.jones@contoso.com"
}

HTTP/1.1 204 No Content

Notes: Doc-derived from Wiki + write-param allowlist; not live-captured. Body fields are Wiki-valid; values are illustrative.

DELETE /exchange/v1.0/distributionGroups/{key}/members/{memberId}/$ref

DELETE /distributionGroups/{key}/members/{memberId}/$ref - Remove-DistributionGroupMember.

Backing cmdlet: Remove-DistributionGroupMember. Role: Group.ReadWrite (Pro).

Parameter	In	Type	Required	Description
`bypassSecurityGroupManagerCheck`	query	bool (switch)
`dryRun`	query	bool (switch)

Remove a member from a distribution group

Sub-resource of GET /distributionGroups/{key}/members/{memberId}. Sub-resource of the distribution group at GET /distributionGroups/{key} - removes a single recipient ({memberId}) from the group’s membership via Remove-DistributionGroupMember. Deleting the link does not delete the recipient.

DELETE /exchange/v1.0/distributionGroups/{key}/members/{memberId}/$ref HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

HTTP/1.1 204 No Content

Notes: Doc-derived from Wiki + write-param allowlist; not live-captured. Body fields are Wiki-valid; values are illustrative.

GET /exchange/v1.0/distributionGroups/{key}/owners

GET /distributionGroups/{key}/owners - owners are the ManagedBy identities; resolve each via Get-Recipient. No dedicated owner cmdlet exists.

Backing cmdlet: Get-Recipient. Role: Group.Read (Community).

List owners of a distribution group

Sub-resource of the DG at GET /distributionGroups/{key}. Owners come from the DG’s ManagedBy field - resolved per-row to a Recipient via Get-Recipient. No dedicated EXO cmdlet exists for owners (this is computed by the API).

GET /exchange/v1.0/distributionGroups/{key}/owners HTTP/1.1
Authorization: Bearer {token}

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#recipients",
  "value": []
}

Notes: To change owners, PATCH the parent DG with a new ManagedBy array - there’s no dedicated POST /owners endpoint.

POST /exchange/v1.0/distributionGroups/{key}/upgrade

POST /distributionGroups/{key}/upgrade - Upgrade-DistributionGroup (EXO-only). Operationally async server-side; poll GET /distributionGroups/{key} for state.

Backing cmdlet: Upgrade-DistributionGroup. Role: Group.ReadWrite (Pro).

Parameter	In	Type	Required	Description
`actionType`	body	string
`executingUser`	body	string

Upgrade a distribution group to a Microsoft 365 Group

Sub-resource of the distribution group at GET /distributionGroups/{key} - migrates the distribution group to a Microsoft 365 Group via Upgrade-DistributionGroup (EXO-only). The URL key is passed as the cmdlet’s -DlIdentities; optional body fields map to -ActionType and -ExecutingUser. Operationally async server-side; poll GET /distributionGroups/{key} for state.

POST /exchange/v1.0/distributionGroups/{key}/upgrade HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "executingUser": "admin@contoso.com"
}

HTTP/1.1 204 No Content

Notes: Doc-derived from Wiki + write-param allowlist; not live-captured. Body fields are Wiki-valid; values are illustrative.

?dryRun=true previews of any write stay on Community.