retentionPolicyTags

Mailbox Retention Tags. Tags that assign delete or archive ages to mailbox folders. The retentionPolicyTags entity set lives under /exchange/v1.0/retentionPolicyTags in the Governance & protection category.

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

Routes

Method	Path	Synopsis	Role	Plan
GET	/exchange/v1.0/retentionPolicyTags	List retentionPolicyTags entries.	Compliance.Read	Community
POST	/exchange/v1.0/retentionPolicyTags	Create a new retentionPolicyTags 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/retentionPolicyTags/{key}	Get a single retentionPolicyTags entry by Identity.	Compliance.Read	Community
PATCH	/exchange/v1.0/retentionPolicyTags/{key}	Partial update of the retentionPolicyTags at /retentionPolicyTags/{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/retentionPolicyTags/{key}	Remove the retentionPolicyTags at /retentionPolicyTags/{key}. Returns 204 with no body.	Compliance.ReadWrite	Enterprise

GET /exchange/v1.0/retentionPolicyTags

List retentionPolicyTags entries.

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

Parameter	In	Type	Required	Description
types	query	string		Filter by folder type (ElcFolderType). Comma-separated; valid values include Inbox, DeletedItems, Personal, All, Calendar, Contacts, Drafts, JunkEmail, Journal, Notes, Outbox, SentItems, Tasks, RssSubscriptions, ConversationHistory. Maps to Get-RetentionPolicyTag -Types; invalid values are rejected by the cmdlet.
includeSystemTags	query	bool (switch)		Also return hidden system tags in addition to personal/default tags. Maps to Get-RetentionPolicyTag -IncludeSystemTags.
mailbox	query	string		Return the retention tags assigned to the retention policy applied to the specified mailbox (name, alias, UPN, email, GUID, etc.). Maps -Mailbox on Get-RetentionPolicyTag; returns only default policy tags and personal tags.
optionalInMailbox	query	bool (switch)		Also return optional retention tags that are available to add to the specified mailbox. Maps Get-RetentionPolicyTag -OptionalInMailbox; used together with -Mailbox.

List retentionPolicyTags

Stub auto-generated example for the retentionPolicyTags collection. Backing cmdlet: Get-RetentionPolicyTag. Live-verify with ?$top=3&$select=Id,Name and replace the synthetic body before promoting to Tier 1.

GET /exchange/v1.0/retentionPolicyTags?$top=3 HTTP/1.1
Authorization: Bearer {token}

HTTP/1.1 200 OK

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

Notes: Illustrative example derived from the cmdlet documentation, not a live capture: field names are real, values are placeholders.

Related: GET /exchange/v1.0/retentionPolicyTags/{key}

POST /exchange/v1.0/retentionPolicyTags

Create a new retentionPolicyTags 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-RetentionPolicyTag. Role: Compliance.ReadWrite (Enterprise).

Parameter	In	Type	Required	Description
name	body		yes
ageLimitForRetention	body
comment	body
localizedComment	body
localizedRetentionPolicyTagName	body
messageClass	body
mustDisplayCommentEnabled	body
retentionAction	body
retentionEnabled	body
retentionId	body
systemTag	body
type	body
dryRun	query	bool (switch)

Create rejected - missing required name

New-RetentionPolicyTag requires a name. Omitting it yields a 400 BadRequest from the body-allowlist validation before the cmdlet runs.

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

{
  "type": "Personal",
  "retentionAction": "DeleteAndAllowRecovery"
}

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": "BadRequest",
    "message": "The required field 'name' is required.",
    "target": "name"
  },
  "correlationId": "0HN7K3M2P9QRS-00000001"
}

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

Related: GET /exchange/v1.0/retentionPolicyTags

Create a retention policy tag

Creates a new retention tag (move-to-archive, delete-and-allow-recovery, etc.) backed by New-RetentionPolicyTag. Returns 201 plus a Location header and the freshly fetched entity.

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

{
  "name": "exonaut-sample-retentionPolicyTags",
  "type": "Personal",
  "retentionAction": "DeleteAndAllowRecovery",
  "ageLimitForRetention": "365.00:00:00",
  "retentionEnabled": true,
  "comment": "Sample personal tag for Exonaut demos"
}

HTTP/1.1 201 Created
Location: /exchange/v1.0/retentionPolicyTags/exonaut-sample-retentionPolicyTags

{
  "Id": "exonaut-sample-retentionPolicyTags",
  "Identity": "exonaut-sample-retentionPolicyTags",
  "Name": "exonaut-sample-retentionPolicyTags",
  "Type": "Personal",
  "RetentionAction": "DeleteAndAllowRecovery",
  "AgeLimitForRetention": "365.00:00:00",
  "RetentionEnabled": true,
  "Comment": "Sample personal tag for Exonaut demos"
}

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

Related: GET /exchange/v1.0/retentionPolicyTags

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

Get a single retentionPolicyTags entry by Identity.

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

Get a single retentionPolicyTags entry

Stub auto-generated example for GET /retentionPolicyTags/{key}. Backing cmdlet: Get-RetentionPolicyTag with -Identity {key}. Returns the full entity body; 404 if the identity doesn’t resolve.

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#retentionPolicyTags/$entity"
}

Notes: Illustrative example derived from the cmdlet documentation, not a live capture: field names are real, values are placeholders.

Related: GET /exchange/v1.0/retentionPolicyTags

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

Partial update of the retentionPolicyTags at /retentionPolicyTags/{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-RetentionPolicyTag. Role: Compliance.ReadWrite (Enterprise).

Parameter	In	Type	Required	Description
ageLimitForRetention	body
comment	body
legacyManagedFolder	body
localizedComment	body
localizedRetentionPolicyTagName	body
mailbox	body
messageClass	body
mustDisplayCommentEnabled	body
name	body
optionalInMailbox	body
retentionAction	body
retentionEnabled	body
retentionId	body
systemTag	body
dryRun	query	bool (switch)

Update a retention policy tag

Partial update of the tag at /retentionPolicyTags/{key} backed by Set-RetentionPolicyTag. Only the body fields present are passed to the cmdlet; returns 200 plus the post-Set entity.

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

{
  "comment": "Updated comment for Exonaut sample tag",
  "ageLimitForRetention": "730.00:00:00",
  "retentionEnabled": true
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Id": "exonaut-sample-retentionPolicyTags",
  "Identity": "exonaut-sample-retentionPolicyTags",
  "Name": "exonaut-sample-retentionPolicyTags",
  "Type": "Personal",
  "RetentionAction": "DeleteAndAllowRecovery",
  "AgeLimitForRetention": "730.00:00:00",
  "RetentionEnabled": true,
  "Comment": "Updated comment for Exonaut sample tag"
}

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

Related: GET /exchange/v1.0/retentionPolicyTags

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

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

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

Parameter	In	Type	Required	Description
dryRun	query	bool (switch)

Delete a retention policy tag

Removes the tag at /retentionPolicyTags/{key} backed by Remove-RetentionPolicyTag. Returns 204 with no body.

DELETE /exchange/v1.0/retentionPolicyTags/{key} 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/retentionPolicyTags

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