recipients

All Recipients. Unified read across every recipient type, plus update action. The recipients entity set lives under /exchange/v1.0/recipients in the Recipients category.

Fact	Value
Path	/exchange/v1.0/recipients
Category	Recipients
Tier	Tier 0, Directory
Read role	Recipient.Read.All (Community)
Write role	Recipient.ReadWrite.All (Pro)
Backing cmdlets	Get-Recipient, Update-Recipient

Routes

Method	Path	Synopsis	Role	Plan
GET	/exchange/v1.0/recipients	List recipients entries.	Recipient.Read	Community
GET	/exchange/v1.0/recipients/{key}	Get a single recipients entry by Identity.	Recipient.Read	Community
POST	/exchange/v1.0/recipients/{key}/update	POST /recipients/{key}/update - bound action that re-stamps the recipient with current org defaults (address lists, OAB, policy assignments). No body. Use after RBAC role / address-list / policy changes that affect this recipient’s projection. Returns 204.	Recipient.ReadWrite	Pro

GET /exchange/v1.0/recipients

List recipients entries.

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

Parameter	In	Type	Required	Description
includeSoftDeletedRecipients	query	bool (switch)		Also include soft-deleted (still-recoverable) recipients in the results. EXO-only, maps Get-Recipient -IncludeSoftDeletedRecipients. Per MS Learn this switch is most effective combined with a $filter on RecipientTypeDetails or a single-recipient lookup.
all	query	bool (switch)		Return all results instead of the EXO default of 1000. Maps -ResultSize Unlimited on Get-Recipient; prevents silent truncation in large tenants.
anr	query	string		Ambiguous name resolution (ANR) search string. Maps -Anr on Get-Recipient; matches a partial string against common name, display name, first/last name, and alias.
recipientTypeDetails	query	string		Filter results by recipient subtype (comma-separated, e.g. UserMailbox,MailUser). Maps -RecipientTypeDetails on Get-Recipient.
recipientType	query	string		Filter by the broad recipient type (comma-separated, e.g. UserMailbox,MailUniversalDistributionGroup). Maps -RecipientType on Get-Recipient.
authenticationType	query	string		Filter by authentication type (Federated | Managed). Maps -AuthenticationType on Get-Recipient.

List recipients (polymorphic across subtypes)

Returns the union of all mail-enabled directory objects - mailboxes, mail users, mail contacts, distribution groups, M365 groups, dynamic DGs, room lists. Each row’s RecipientTypeDetails identifies the subtype. Most-trafficked endpoint for cross-type lookups.

GET /exchange/v1.0/recipients?$top=3&$select=Id,DisplayName,PrimarySmtpAddress,RecipientTypeDetails HTTP/1.1
Authorization: Bearer {token}

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#recipients(Id,DisplayName,PrimarySmtpAddress,RecipientTypeDetails)",
  "value": [
    {
      "@odata.type": "#ExchangeApi.SharedMailbox",
      "Id": "_TestUser",
      "DisplayName": "_TestUser",
      "PrimarySmtpAddress": "[email protected]",
      "RecipientTypeDetails": "SharedMailbox"
    },
    {
      "@odata.type": "#ExchangeApi.SharedMailbox",
      "Id": "[Forward]",
      "DisplayName": "[Forward]",
      "PrimarySmtpAddress": "[email protected]",
      "RecipientTypeDetails": "SharedMailbox"
    },
    {
      "@odata.type": "#ExchangeApi.GroupMailbox",
      "Id": "engineering_b01e5307-2265-49d4-99ad-0a3f9378929c",
      "DisplayName": "engineering_lori",
      "PrimarySmtpAddress": "[email protected]",
      "RecipientTypeDetails": "GroupMailbox"
    }
  ]
}

Notes: Use this when you don’t know which subtype an SMTP belongs to. Once you do, prefer the typed endpoint (/mailboxes/{x}, /distributionGroups/{x}) for richer per-subtype fields.

Related: GET /exchange/v1.0/recipients/{key}, GET /exchange/v1.0/mailboxes, GET /exchange/v1.0/mailContacts, GET /exchange/v1.0/mailUsers, GET /exchange/v1.0/distributionGroups, GET /exchange/v1.0/unifiedGroups

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

Get a single recipients entry by Identity.

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

POST /exchange/v1.0/recipients/{key}/update

POST /recipients/{key}/update - bound action that re-stamps the recipient with current org defaults (address lists, OAB, policy assignments). No body. Use after RBAC role / address-list / policy changes that affect this recipient’s projection. Returns 204.

Backing cmdlet: Update-Recipient. Role: Recipient.ReadWrite (Pro).

Parameter	In	Type	Required	Description
dryRun	query	bool (switch)

Re-stamp a recipient with current organization defaults

Sub-resource of the recipient at GET /recipients/{key} - bound action backed by Update-Recipient. Re-applies current org defaults (address lists, offline address book, and policy assignments) to the recipient after RBAC role, address-list, or policy changes. Takes no body and returns 204 No Content.

POST /exchange/v1.0/recipients/{key}/update 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.

Related: GET /exchange/v1.0/recipients

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