retentionPolicies

Mailbox Retention Policies. Messaging records management policies that group mailbox retention tags. The retentionPolicies entity set lives under /exchange/v1.0/retentionPolicies in the Governance & protection category.

Fact	Value
Path	`/exchange/v1.0/retentionPolicies`
Category	Governance & protection
Tier	Tier 9, Hybrid and organization
Read role	`Compliance.Read.All` (Community)
Write role	`Compliance.ReadWrite.All` (Enterprise)
Backing cmdlets	Get-RetentionPolicy, Set-RetentionPolicy, New-RetentionPolicy, Remove-RetentionPolicy

Routes

Method	Path	Synopsis	Role	Plan
GET	`/exchange/v1.0/retentionPolicies`	List retentionPolicies entries.	`Compliance.Read`	Community
POST	`/exchange/v1.0/retentionPolicies`	Create a new retentionPolicies entry. Body keys map 1:1 to the cmdlet’s parameter names (camelCased). Returns 201 + Location + the freshly-fetched entity. Use ?dryRun=true to map to -WhatIf without applying.	`Compliance.ReadWrite`	Enterprise
GET	`/exchange/v1.0/retentionPolicies/{key}`	Get a single retentionPolicies entry by Identity.	`Compliance.Read`	Community
PATCH	`/exchange/v1.0/retentionPolicies/{key}`	Partial update of the retentionPolicies at /retentionPolicies/{key}. Only body fields present are passed to the cmdlet. Returns 200 + the post-Set entity (rename-aware re-fetch when `name` is in the body).	`Compliance.ReadWrite`	Enterprise
DELETE	`/exchange/v1.0/retentionPolicies/{key}`	Remove the retentionPolicies at /retentionPolicies/{key}. Returns 204 with no body.	`Compliance.ReadWrite`	Enterprise

GET /exchange/v1.0/retentionPolicies

List retentionPolicies entries.

Backing cmdlet: Get-RetentionPolicy. Role: Compliance.Read (Community).

List retention policies

List all Messaging Records Management (MRM) retention policies in the organization, including the retention tags each one links and which policy is the tenant default.

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#retentionPolicies",
  "value": [
    {
      "Id": "ArbitrationMailbox",
      "Name": "ArbitrationMailbox",
      "AdminDisplayName": "",
      "DistinguishedName": "CN=ArbitrationMailbox,CN=Retention Policies Container,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
      "ExchangeObjectId": "9a1f4c0e-5b27-4d83-8e11-2c6f7a90d3b4",
      "Guid": "3d8e7b21-6c4a-4f59-9a02-1e5b8c47f6a0",
      "Identity": "ArbitrationMailbox",
      "IsDefault": false,
      "IsDefaultArbitrationMailbox": true,
      "OrganizationalUnitRoot": "contoso.onmicrosoft.com",
      "OrganizationId": "EURPR01A017.PROD.OUTLOOK.COM/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com - EURPR01A017.PROD.OUTLOOK.COM/ConfigurationUnits/contoso.onmicrosoft.com/Configuration",
      "RetentionId": "3d8e7b21-6c4a-4f59-9a02-1e5b8c47f6a0",
      "RetentionPolicyTagLinks": "Never Delete AsyncOperationNotification ModeratedRecipients AutoGroup",
      "WhenChanged": "2026-03-30T17:40:29+03:00",
      "WhenChangedUTC": "2026-03-30T14:40:29Z",
      "WhenCreated": "2026-03-30T17:40:21+03:00",
      "WhenCreatedUTC": "2026-03-30T14:40:21Z"
    },
    {
      "Id": "Default MRM Policy",
      "Name": "Default MRM Policy",
      "AdminDisplayName": "",
      "DistinguishedName": "CN=Default MRM Policy,CN=Retention Policies Container,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
      "ExchangeObjectId": "b2c7d519-8e34-4a61-9f0d-72a1e6c4b830",
      "Guid": "e4f0a96b-1d27-4c83-8b50-9a6f3d215e74",
      "Identity": "Default MRM Policy",
      "IsDefault": true,
      "IsDefaultArbitrationMailbox": false,
      "OrganizationalUnitRoot": "contoso.onmicrosoft.com",
      "OrganizationId": "EURPR01A017.PROD.OUTLOOK.COM/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com - EURPR01A017.PROD.OUTLOOK.COM/ConfigurationUnits/contoso.onmicrosoft.com/Configuration",
      "RetentionId": "e4f0a96b-1d27-4c83-8b50-9a6f3d215e74",
      "RetentionPolicyTagLinks": "Recoverable Items 14 days move to archive Junk Email Default 2 year move to archive Personal 1 year move to archive Personal never move to archive 1 Week Delete 1 Month Delete Personal 5 year move to archive 6 Month Delete 1 Year Delete 5 Year Delete Never Delete",
      "WhenChanged": "2026-03-30T17:40:47+03:00",
      "WhenChangedUTC": "2026-03-30T14:40:47Z",
      "WhenCreated": "2026-03-30T17:06:56+03:00",
      "WhenCreatedUTC": "2026-03-30T14:06:56Z"
    },
    {
      "Id": "New MRM policy",
      "Name": "New MRM policy",
      "AdminDisplayName": "",
      "DistinguishedName": "CN=New MRM policy,CN=Retention Policies Container,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
      "ExchangeObjectId": "c8d3f60a-4b91-4d27-8e63-1f5a9c70e2b4",
      "Guid": "7a2e1d4c-9b58-4f03-86d1-3c6b8e547f02",
      "Identity": "New MRM policy",
      "IsDefault": false,
      "IsDefaultArbitrationMailbox": false,
      "OrganizationalUnitRoot": "contoso.onmicrosoft.com",
      "OrganizationId": "EURPR01A017.PROD.OUTLOOK.COM/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com - EURPR01A017.PROD.OUTLOOK.COM/ConfigurationUnits/contoso.onmicrosoft.com/Configuration",
      "RetentionId": "7a2e1d4c-9b58-4f03-86d1-3c6b8e547f02",
      "RetentionPolicyTagLinks": "7-day Delete",
      "WhenChanged": "2026-03-30T17:44:24+03:00",
      "WhenChangedUTC": "2026-03-30T14:44:24Z",
      "WhenCreated": "2026-03-30T17:44:11+03:00",
      "WhenCreatedUTC": "2026-03-30T14:44:11Z"
    }
  ]
}

POST /exchange/v1.0/retentionPolicies

Create a new retentionPolicies entry. Body keys map 1:1 to the cmdlet’s parameter names (camelCased). Returns 201 + Location + the freshly-fetched entity. Use ?dryRun=true to map to -WhatIf without applying.

Backing cmdlet: New-RetentionPolicy. Role: Compliance.ReadWrite (Enterprise).

Parameter	In	Type	Required
`name`	body		yes
`isDefault`	body	boolean (switch)
`retentionId`	body
`retentionPolicyTagLinks`	body
`dryRun`	query	bool (switch)

Create mrm retention policy - duplicate (409)

MRM retention policy create returns 409 when an object of that name already exists. Backed by New-RetentionPolicy.

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

{
  "name": "exonaut-audit-retpol"
}

HTTP/1.1 409 Conflict

{
  "error": {
    "code": "Conflict",
    "message": "Cmdlet 'New-RetentionPolicy' failed: ||Active Directory operation failed on VI1PR01A17DC001.EURPR01A017.PROD.OUTLOOK.COM. The object 'CN=exonaut-audit-retpol,CN=Retention Policies Container,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM' already exists.",
    "target": null,
    "innerError": {
      "cmdlet": "New-RetentionPolicy"
    }
  },
  "correlationId": "0HNLTJ0Q1D32K:00000001"
}

Create a mrm retention policy

MRM retention policy create. Returns 201 + Location + the freshly-fetched object. Backed by New-RetentionPolicy.

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

{
  "name": "exonaut-audit-retpol"
}

HTTP/1.1 201 Created
Location: /exchange/v1.0/retentionPolicies/exonaut-audit-retpol

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#retentionPolicies/$entity",
  "Id": "exonaut-audit-retpol",
  "Name": "exonaut-audit-retpol",
  "AdminDisplayName": "",
  "DistinguishedName": "CN=exonaut-audit-retpol,CN=Retention Policies Container,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
  "ExchangeObjectId": "994e712e-91ed-4e27-a4ec-9ca795e577be",
  "Guid": "994e712e-91ed-4e27-a4ec-9ca795e577be",
  "Identity": "exonaut-audit-retpol",
  "IsDefault": false,
  "IsDefaultArbitrationMailbox": false,
  "OrganizationalUnitRoot": "contoso.onmicrosoft.com",
  "OrganizationId": "EURPR01A017.PROD.OUTLOOK.COM/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com - EURPR01A017.PROD.OUTLOOK.COM/ConfigurationUnits/contoso.onmicrosoft.com/Configuration",
  "RetentionId": "994e712e-91ed-4e27-a4ec-9ca795e577be",
  "RetentionPolicyTagLinks": null,
  "WhenChanged": "2026-05-29T18:45:20+03:00",
  "WhenChangedUTC": "2026-05-29T15:45:20Z",
  "WhenCreated": "2026-05-29T18:45:20+03:00",
  "WhenCreatedUTC": "2026-05-29T15:45:20Z"
}

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

Get a single retentionPolicies entry by Identity.

Backing cmdlet: Get-RetentionPolicy. Role: Compliance.Read (Community).

Get a retention policy by identity

Retrieve a single Messaging Records Management (MRM) retention policy by its Identity, including the retention tags it links.

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#retentionPolicies/$entity",
  "Id": "ArbitrationMailbox",
  "Name": "ArbitrationMailbox",
  "AdminDisplayName": "",
  "DistinguishedName": "CN=ArbitrationMailbox,CN=Retention Policies Container,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
  "ExchangeObjectId": "9a1f4c0e-5b27-4d83-8e11-2c6f7a90d3b4",
  "Guid": "3d8e7b21-6c4a-4f59-9a02-1e5b8c47f6a0",
  "Identity": "ArbitrationMailbox",
  "IsDefault": false,
  "IsDefaultArbitrationMailbox": true,
  "OrganizationalUnitRoot": "contoso.onmicrosoft.com",
  "OrganizationId": "EURPR01A017.PROD.OUTLOOK.COM/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com - EURPR01A017.PROD.OUTLOOK.COM/ConfigurationUnits/contoso.onmicrosoft.com/Configuration",
  "RetentionId": "3d8e7b21-6c4a-4f59-9a02-1e5b8c47f6a0",
  "RetentionPolicyTagLinks": "Never Delete AsyncOperationNotification ModeratedRecipients AutoGroup",
  "WhenChanged": "2026-03-30T17:40:29+03:00",
  "WhenChangedUTC": "2026-03-30T14:40:29Z",
  "WhenCreated": "2026-03-30T17:40:21+03:00",
  "WhenCreatedUTC": "2026-03-30T14:40:21Z"
}

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

Partial update of the retentionPolicies at /retentionPolicies/{key}. Only body fields present are passed to the cmdlet. Returns 200 + the post-Set entity (rename-aware re-fetch when name is in the body).

Backing cmdlet: Set-RetentionPolicy. Role: Compliance.ReadWrite (Enterprise).

Parameter	In	Type
`isDefault`	body	boolean (switch)
`isDefaultArbitrationMailbox`	body	boolean (switch)
`name`	body
`retentionId`	body
`retentionPolicyTagLinks`	body
`dryRun`	query	bool (switch)

Rename a retention policy

Set-RetentionPolicy with -Name renames in-place. WriteControllerBase’s rename-aware re-fetch tries the new Name first, then falls back to URL {key} so the response reflects the renamed entity (post-slice-18 fix). Returns 200.

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

{
  "name": "compliance-baseline-v2"
}

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#retentionPolicies/$entity",
  "Id": "compliance-baseline-v2",
  "Name": "compliance-baseline-v2"
}

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

Remove the retentionPolicies at /retentionPolicies/{key}. Returns 204 with no body.

Backing cmdlet: Remove-RetentionPolicy. Role: Compliance.ReadWrite (Enterprise).

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

Delete a mrm retention policy

Removes the mrm retention policy by Identity. Returns 204. Backed by Remove-RetentionPolicy.

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

HTTP/1.1 204 No Content

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