safeAttachmentPolicies

Safe Attachments Policies. Defender policies that sandbox email attachments to catch malware. The safeAttachmentPolicies entity set lives under /exchange/v1.0/safeAttachmentPolicies in the Threat protection category.

Fact	Value
Path	`/exchange/v1.0/safeAttachmentPolicies`
Category	Threat protection
Tier	Tier 4, Threat protection
Read role	`ThreatPolicy.Read.All` (Community)
Write role	`ThreatPolicy.ReadWrite.All` (Enterprise)
Backing cmdlets	Get-SafeAttachmentPolicy, Set-SafeAttachmentPolicy, New-SafeAttachmentPolicy, Remove-SafeAttachmentPolicy

Routes

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

GET /exchange/v1.0/safeAttachmentPolicies

List safeAttachmentPolicies entries.

Backing cmdlet: Get-SafeAttachmentPolicy. Role: ThreatPolicy.Read (Community).

List Safe Attachment policies

Returns the tenant’s Safe Attachments policies (Microsoft Defender for Office 365). Backed by Get-SafeAttachmentPolicy; supports OData paging via $top.

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#safeAttachmentPolicies",
  "value": [
    {
      "Id": "Built-In Protection Policy",
      "Name": "Built-In Protection Policy",
      "Identity": "Built-In Protection Policy",
      "AdminDisplayName": "",
      "Guid": "28b2cc6e-d52b-4b3b-8e7f-8aaab2922c26",
      "IsEnabled": false,
      "IsBuiltInProtection": true,
      "Enable": true,
      "Action": "Block",
      "Redirect": "False",
      "RedirectAddress": "",
      "ActionOnError": null,
      "QuarantineTag": false,
      "EnableInternalSenderAdminNotifications": false,
      "InternalSenderAdminAddress": null,
      "EnableExternalSenderAdminNotifications": false,
      "ExternalSenderAdminAddress": null,
      "EnableOrganizationBranding": false,
      "WhenCreated": "2026-03-30T17:42:21+03:00",
      "WhenChanged": "2026-03-30T17:42:35+03:00",
      "DistinguishedName": "CN=Built-In Protection Policy,CN=Safe Attachment,CN=Transport Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
      "EnableBlockingEncryptedAttachments": false,
      "ExchangeObjectId": "2a9d52cf-2313-48d0-bc17-7f4172d5dc13",
      "ExcludedTypesFromBlockingEncryptedAttachments": [],
      "IsDefault": false,
      "OrganizationId": "EURPR01A017.PROD.OUTLOOK.COM/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com - EURPR01A017.PROD.OUTLOOK.COM/ConfigurationUnits/contoso.onmicrosoft.com/Configuration",
      "OrganizationalUnitRoot": "contoso.onmicrosoft.com",
      "QuarantineTagForBlockingEncryptedAttachments": "DefaultFullAccessWithNotificationPolicy",
      "RecommendedPolicyType": "Custom",
      "WhenChangedUTC": "2026-03-30T14:42:35Z",
      "WhenCreatedUTC": "2026-03-30T14:42:21Z"
    },
    {
      "Id": "Enforce Safe Attachments (Global)",
      "Name": "Enforce Safe Attachments (Global)",
      "Identity": "Enforce Safe Attachments (Global)",
      "AdminDisplayName": "",
      "Guid": "d995f7bc-cbdf-42f1-b137-79741b75b2ce",
      "IsEnabled": false,
      "IsBuiltInProtection": false,
      "Enable": true,
      "Action": "Block",
      "Redirect": "False",
      "RedirectAddress": "",
      "ActionOnError": null,
      "QuarantineTag": false,
      "EnableInternalSenderAdminNotifications": false,
      "InternalSenderAdminAddress": null,
      "EnableExternalSenderAdminNotifications": false,
      "ExternalSenderAdminAddress": null,
      "EnableOrganizationBranding": false,
      "WhenCreated": "2026-03-30T17:42:30+03:00",
      "WhenChanged": "2026-03-30T17:42:36+03:00",
      "DistinguishedName": "CN=Enforce Safe Attachments (Global),CN=Safe Attachment,CN=Transport Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
      "EnableBlockingEncryptedAttachments": false,
      "ExchangeObjectId": "cc43e0a9-72df-42aa-8ae4-a0bfff4a0e9d",
      "ExcludedTypesFromBlockingEncryptedAttachments": [],
      "IsDefault": false,
      "OrganizationId": "EURPR01A017.PROD.OUTLOOK.COM/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com - EURPR01A017.PROD.OUTLOOK.COM/ConfigurationUnits/contoso.onmicrosoft.com/Configuration",
      "OrganizationalUnitRoot": "contoso.onmicrosoft.com",
      "QuarantineTagForBlockingEncryptedAttachments": "DefaultFullAccessWithNotificationPolicy",
      "RecommendedPolicyType": "Custom",
      "WhenChangedUTC": "2026-03-30T14:42:36Z",
      "WhenCreatedUTC": "2026-03-30T14:42:30Z"
    }
  ]
}

Notes: IsBuiltInProtection=true marks the Microsoft-managed preset policy, which is read-only. WhenCreatedUTC/WhenChangedUTC mirror the local-time WhenCreated/WhenChanged.

POST /exchange/v1.0/safeAttachmentPolicies

Create a new safeAttachmentPolicies 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-SafeAttachmentPolicy. Role: ThreatPolicy.ReadWrite (Enterprise).

Parameter	In	Type	Required
`name`	body		yes
`action`	body
`adminDisplayName`	body
`enable`	body
`quarantineTag`	body
`redirect`	body
`redirectAddress`	body
`dryRun`	query	bool (switch)

Create safeAttachmentPolicies - duplicate name (409)

Safe Attachments policy create fails with 409 when a policy of that name already exists. Backed by New-SafeAttachmentPolicy.

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

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

HTTP/1.1 409 Conflict

{
  "error": {
    "code": "Conflict",
    "message": "Cmdlet 'New-SafeAttachmentPolicy' failed: ||Safe attachment policy 'exonaut-audit-safeattach' already exists.",
    "target": null,
    "innerError": {
      "cmdlet": "New-SafeAttachmentPolicy"
    }
  },
  "correlationId": "0HNLTIGH3TLO5:00000001"
}

Create a safeAttachmentPolicie

Safe Attachments policy create. Required: name. Returns 201 + Location + the freshly-fetched policy. Backed by New-SafeAttachmentPolicy.

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

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

HTTP/1.1 201 Created
Location: /exchange/v1.0/safeAttachmentPolicies/exonaut-audit-safeattach

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#safeAttachmentPolicies/$entity",
  "Id": "exonaut-audit-safeattach",
  "Name": "exonaut-audit-safeattach",
  "Identity": "exonaut-audit-safeattach",
  "AdminDisplayName": "",
  "Guid": "cbb53edf-3f11-4556-91e3-38b7440004ae",
  "IsEnabled": false,
  "IsBuiltInProtection": false,
  "Enable": false,
  "Action": "Block",
  "Redirect": "False",
  "RedirectAddress": "",
  "ActionOnError": null,
  "QuarantineTag": "AdminOnlyAccessPolicy",
  "EnableInternalSenderAdminNotifications": false,
  "InternalSenderAdminAddress": null,
  "EnableExternalSenderAdminNotifications": false,
  "ExternalSenderAdminAddress": null,
  "EnableOrganizationBranding": false,
  "WhenCreated": "2026-05-29T18:34:47+03:00",
  "WhenChanged": "2026-05-29T18:34:47+03:00",
  "DistinguishedName": "CN=exonaut-audit-safeattach,CN=Safe Attachment,CN=Transport Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
  "EnableBlockingEncryptedAttachments": false,
  "ExchangeObjectId": "cbb53edf-3f11-4556-91e3-38b7440004ae",
  "ExcludedTypesFromBlockingEncryptedAttachments": [],
  "IsDefault": false,
  "OrganizationId": "EURPR01A017.PROD.OUTLOOK.COM/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com - EURPR01A017.PROD.OUTLOOK.COM/ConfigurationUnits/contoso.onmicrosoft.com/Configuration",
  "OrganizationalUnitRoot": "contoso.onmicrosoft.com",
  "QuarantineTagForBlockingEncryptedAttachments": "DefaultFullAccessWithNotificationPolicy",
  "RecommendedPolicyType": "Custom",
  "WhenChangedUTC": "2026-05-29T15:34:47Z",
  "WhenCreatedUTC": "2026-05-29T15:34:47Z"
}

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

Get a single safeAttachmentPolicies entry by Identity.

Backing cmdlet: Get-SafeAttachmentPolicy. Role: ThreatPolicy.Read (Community).

Get a single Safe Attachment policy

Returns one Safe Attachments policy by identity. Backed by Get-SafeAttachmentPolicy with -Identity {key}; returns the full entity body.

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#safeAttachmentPolicies/$entity",
  "Id": "Built-In Protection Policy",
  "Name": "Built-In Protection Policy",
  "Identity": "Built-In Protection Policy",
  "AdminDisplayName": "",
  "Guid": "28b2cc6e-d52b-4b3b-8e7f-8aaab2922c26",
  "IsEnabled": false,
  "IsBuiltInProtection": true,
  "Enable": true,
  "Action": "Block",
  "Redirect": "False",
  "RedirectAddress": "",
  "ActionOnError": null,
  "QuarantineTag": false,
  "EnableInternalSenderAdminNotifications": false,
  "InternalSenderAdminAddress": null,
  "EnableExternalSenderAdminNotifications": false,
  "ExternalSenderAdminAddress": null,
  "EnableOrganizationBranding": false,
  "WhenCreated": "2026-03-30T17:42:21+03:00",
  "WhenChanged": "2026-03-30T17:42:35+03:00",
  "DistinguishedName": "CN=Built-In Protection Policy,CN=Safe Attachment,CN=Transport Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
  "EnableBlockingEncryptedAttachments": false,
  "ExchangeObjectId": "2a9d52cf-2313-48d0-bc17-7f4172d5dc13",
  "ExcludedTypesFromBlockingEncryptedAttachments": [],
  "IsDefault": false,
  "OrganizationId": "EURPR01A017.PROD.OUTLOOK.COM/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com - EURPR01A017.PROD.OUTLOOK.COM/ConfigurationUnits/contoso.onmicrosoft.com/Configuration",
  "OrganizationalUnitRoot": "contoso.onmicrosoft.com",
  "QuarantineTagForBlockingEncryptedAttachments": "DefaultFullAccessWithNotificationPolicy",
  "RecommendedPolicyType": "Custom",
  "WhenChangedUTC": "2026-03-30T14:42:35Z",
  "WhenCreatedUTC": "2026-03-30T14:42:21Z"
}

Notes: The {key} is the policy Identity/Name (e.g. “Built-In Protection Policy”). Built-in protection policies are Microsoft-managed and read-only.

Get a single safeAttachmentPolicies entry - not found

Returns a 404 with the canonical error envelope when the supplied identity does not resolve to a Safe Attachments policy. Backed by Get-SafeAttachmentPolicy with -Identity {key}.

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

HTTP/1.1 404 Not Found

{
  "error": {
    "code": "NotFound",
    "message": "Exchange object 'does-not-exist-12345' could not be found.",
    "target": "identity",
    "innerError": {
      "cmdlet": "Get-SafeAttachmentPolicy"
    }
  },
  "correlationId": "0HNLSU6PPVJ03:00000001"
}

Notes: The {key} must match an existing policy Identity/Name; an unresolved identity yields this 404 envelope. correlationId is per-request and will differ.

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

Partial update of the safeAttachmentPolicies at /safeAttachmentPolicies/{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-SafeAttachmentPolicy. Role: ThreatPolicy.ReadWrite (Enterprise).

Parameter	In	Type
`action`	body
`adminDisplayName`	body
`enable`	body
`quarantineTag`	body
`redirect`	body
`redirectAddress`	body
`dryRun`	query	bool (switch)

Update a Safe Attachments policy

Partially update the Safe Attachments policy at /safeAttachmentPolicies/{key} via the Set-SafeAttachmentPolicy cmdlet. Only the body fields present are passed to the cmdlet; returns 200 with the post-Set entity.

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

{
  "action": "Block",
  "enable": true,
  "redirect": true,
  "redirectAddress": "[email protected]"
}

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

{
  "Identity": "exonaut-sample-safeAttachmentPolicies",
  "Name": "exonaut-sample-safeAttachmentPolicies",
  "Action": "Block",
  "Enable": true,
  "Redirect": true,
  "RedirectAddress": "[email protected]"
}

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

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

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

Backing cmdlet: Remove-SafeAttachmentPolicy. Role: ThreatPolicy.ReadWrite (Enterprise).

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

Delete a safeAttachmentPolicie

Removes the policy by Identity. Returns 204. Backed by Remove-SafeAttachmentPolicy.

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

HTTP/1.1 204 No Content

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