messageClassifications

Message Classifications. Custom labels users apply to messages, enforced by transport rules. The messageClassifications entity set lives under /exchange/v1.0/messageClassifications in the Mail flow category.

Fact	Value
Path	/exchange/v1.0/messageClassifications
Category	Mail flow
Tier	Tier 3, Mail flow
Read role	MailFlow.Read.All (Community)
Write role	MailFlow.ReadWrite.All (Pro)
Backing cmdlets	Get-MessageClassification, Set-MessageClassification, New-MessageClassification, Remove-MessageClassification

Routes

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

GET /exchange/v1.0/messageClassifications

List messageClassifications entries.

Backing cmdlet: Get-MessageClassification. Role: MailFlow.Read (Community).

Parameter	In	Type	Required	Description
includeLocales	query	bool (switch)		Return locale-specific child classifications in the results (Get-MessageClassification -IncludeLocales). Surfaces localized sibling classifications for multilingual setups.

List messageClassifications

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

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#messageClassifications",
  "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/messageClassifications/{key}

POST /exchange/v1.0/messageClassifications

Create a new messageClassifications 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-MessageClassification. Role: MailFlow.ReadWrite (Pro).

Parameter	In	Type	Required	Description
displayName	body		yes
name	body		yes
senderDescription	body		yes
classificationID	body
displayPrecedence	body
locale	body
permissionMenuVisible	body
recipientDescription	body
retainClassificationEnabled	body
dryRun	query	bool (switch)

Create a message classification - missing required field

New-MessageClassification requires name, displayName and senderDescription. Omitting senderDescription (or any required field) yields a 400 BadRequest from the body-allowlist validation before the cmdlet runs.

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

{
  "name": "exonaut-sample-messageClassifications",
  "displayName": "EXONAUT Confidential"
}

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

{
  "error": {
    "code": "BadRequest",
    "message": "The field 'senderDescription' is required for New-MessageClassification.",
    "target": "senderDescription"
  },
  "correlationId": "0HN3K8M2P9QABC"
}

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

Related: GET /exchange/v1.0/messageClassifications

Create a message classification

Creates a new Outlook message classification tag via New-MessageClassification. Body keys map 1:1 to the cmdlet’s parameter names (camelCased); Name, displayName and senderDescription are required.

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

{
  "name": "exonaut-sample-messageClassifications",
  "displayName": "EXONAUT Confidential",
  "senderDescription": "Marks messages as EXONAUT confidential before sending.",
  "recipientDescription": "This message has been classified as EXONAUT confidential.",
  "displayPrecedence": "Highest",
  "permissionMenuVisible": true,
  "retainClassificationEnabled": true
}

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

{
  "Id": "exonaut-sample-messageClassifications",
  "Identity": "exonaut-sample-messageClassifications",
  "name": "exonaut-sample-messageClassifications",
  "displayName": "EXONAUT Confidential",
  "senderDescription": "Marks messages as EXONAUT confidential before sending.",
  "recipientDescription": "This message has been classified as EXONAUT confidential.",
  "displayPrecedence": "Highest",
  "permissionMenuVisible": true,
  "retainClassificationEnabled": true
}

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

Related: GET /exchange/v1.0/messageClassifications

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

Get a single messageClassifications entry by Identity.

Backing cmdlet: Get-MessageClassification. Role: MailFlow.Read (Community).

Parameter	In	Type	Required	Description
includeLocales	query	bool (switch)		Return locale-specific child classifications in the results (Get-MessageClassification -IncludeLocales). Surfaces localized sibling classifications for multilingual setups.

Get a single messageClassifications entry

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

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#messageClassifications/$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/messageClassifications

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

Partial update of the messageClassifications at /messageClassifications/{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-MessageClassification. Role: MailFlow.ReadWrite (Pro).

Parameter	In	Type	Required	Description
classificationID	body
displayName	body
displayPrecedence	body
name	body
permissionMenuVisible	body
recipientDescription	body
retainClassificationEnabled	body
senderDescription	body
dryRun	query	bool (switch)

Update a message classification

Sub-resource of the messageClassifications entity at GET /messageClassifications/{key} - partial update via Set-MessageClassification. Only body fields present are passed to the cmdlet; returns 200 with the post-Set entity (rename-aware re-fetch when name is in the body).

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

{
  "displayName": "EXONAUT Confidential (Updated)",
  "senderDescription": "Updated guidance for EXONAUT confidential messages.",
  "displayPrecedence": "High"
}

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

{
  "Id": "exonaut-sample-messageClassifications",
  "Identity": "exonaut-sample-messageClassifications",
  "name": "exonaut-sample-messageClassifications",
  "displayName": "EXONAUT Confidential (Updated)",
  "senderDescription": "Updated guidance for EXONAUT confidential messages.",
  "displayPrecedence": "High",
  "permissionMenuVisible": true,
  "retainClassificationEnabled": true
}

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

Related: GET /exchange/v1.0/messageClassifications

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

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

Backing cmdlet: Remove-MessageClassification. Role: MailFlow.ReadWrite (Pro).

Parameter	In	Type	Required	Description
dryRun	query	bool (switch)

Delete a message classification

Sub-resource of the messageClassifications entity at GET /messageClassifications/{key} - removes the classification via Remove-MessageClassification. Returns 204 with no body.

DELETE /exchange/v1.0/messageClassifications/{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/messageClassifications

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