safeLinksPolicies

Safe Links Policies. Defender policies that rewrite and scan URLs in email. The safeLinksPolicies entity set lives under /exchange/v1.0/safeLinksPolicies in the Threat protection category.

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

Routes

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

GET /exchange/v1.0/safeLinksPolicies

List safeLinksPolicies entries.

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

List Safe Links policies

Returns the tenant’s Safe Links policies, which control time-of-click URL protection for Microsoft Defender for Office 365. Backed by the Get-SafeLinksPolicy cmdlet.

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#safeLinksPolicies",
  "value": [
    {
      "Id": "Built-In Protection Policy",
      "Name": "Built-In Protection Policy",
      "Identity": "Built-In Protection Policy",
      "AdminDisplayName": "",
      "Guid": "71a63616-9bbd-42fe-96da-2041b53db5f0",
      "IsEnabled": false,
      "IsBuiltInProtection": true,
      "EnableSafeLinksForEmail": true,
      "EnableSafeLinksForTeams": true,
      "EnableSafeLinksForOffice": true,
      "ScanUrls": true,
      "DeliverMessageAfterScan": true,
      "EnableForInternalSenders": false,
      "TrackClicks": true,
      "AllowClickThrough": true,
      "DisableUrlRewrite": true,
      "EnableOrganizationBranding": false,
      "CustomNotificationText": "",
      "DoNotRewriteUrls": [],
      "WhenCreated": "2026-03-30T17:42:16+03:00",
      "WhenChanged": "2026-03-30T17:42:26+03:00",
      "CustomUrlList": [],
      "DistinguishedName": "CN=Built-In Protection Policy,CN=Safe Links,CN=Transport Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
      "ExchangeObjectId": "d2065168-768f-4ec2-9e0e-e0bfda7d3186",
      "LocalizedNotificationTextList": [],
      "LocalizedUrlTextList": [],
      "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",
      "RecommendedPolicyType": "Custom",
      "WhenChangedUTC": "2026-03-30T14:42:26Z",
      "WhenCreatedUTC": "2026-03-30T14:42:16Z"
    },
    {
      "Id": "Enforce Safe Links (Global)",
      "Name": "Enforce Safe Links (Global)",
      "Identity": "Enforce Safe Links (Global)",
      "AdminDisplayName": "",
      "Guid": "3da7fabf-e830-4588-b9ae-fa45f39c5353",
      "IsEnabled": false,
      "IsBuiltInProtection": false,
      "EnableSafeLinksForEmail": true,
      "EnableSafeLinksForTeams": true,
      "EnableSafeLinksForOffice": true,
      "ScanUrls": true,
      "DeliverMessageAfterScan": false,
      "EnableForInternalSenders": true,
      "TrackClicks": true,
      "AllowClickThrough": false,
      "DisableUrlRewrite": false,
      "EnableOrganizationBranding": true,
      "CustomNotificationText": "",
      "DoNotRewriteUrls": [],
      "WhenCreated": "2026-03-30T17:42:44+03:00",
      "WhenChanged": "2026-03-30T17:42:53+03:00",
      "CustomUrlList": [],
      "DistinguishedName": "CN=Enforce Safe Links (Global),CN=Safe Links,CN=Transport Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
      "ExchangeObjectId": "8cc25317-1b49-40ef-a385-0ed547a89797",
      "LocalizedNotificationTextList": [],
      "LocalizedUrlTextList": [],
      "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",
      "RecommendedPolicyType": "Custom",
      "WhenChangedUTC": "2026-03-30T14:42:53Z",
      "WhenCreatedUTC": "2026-03-30T14:42:44Z"
    }
  ]
}

Notes: Safe Links policies pair with Safe Links rules; the policy holds the protection settings while the rule scopes them to recipients. The Built-In Protection Policy is read-only and managed by Microsoft.

POST /exchange/v1.0/safeLinksPolicies

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

Parameter	In	Type	Required
`name`	body		yes
`adminDisplayName`	body
`allowClickThrough`	body
`customNotificationText`	body
`deliverMessageAfterScan`	body
`disableUrlRewrite`	body
`doNotRewriteUrls`	body
`enableForInternalSenders`	body
`enableOrganizationBranding`	body
`enableSafeLinksForEmail`	body
`enableSafeLinksForOffice`	body
`enableSafeLinksForTeams`	body
`scanUrls`	body
`trackClicks`	body
`useTranslatedNotificationText`	body
`dryRun`	query	bool (switch)

Create safe links policy - duplicate (409)

Safe Links policy create returns 409 when an object of that name already exists. Backed by New-SafeLinksPolicy.

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

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

HTTP/1.1 409 Conflict

{
  "error": {
    "code": "Conflict",
    "message": "Cmdlet 'New-SafeLinksPolicy' failed: ||Active Directory operation failed on VI1PR01A17DC001.EURPR01A017.PROD.OUTLOOK.COM. The object 'CN=exonaut-audit-safelinks,CN=Safe Links,CN=Transport Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM' already exists.",
    "target": null,
    "innerError": {
      "cmdlet": "New-SafeLinksPolicy"
    }
  },
  "correlationId": "0HNLTJ0Q1D326:00000001"
}

Create a safe links policy

Safe Links policy create. Returns 201 + Location + the freshly-fetched object. Backed by New-SafeLinksPolicy.

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

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

HTTP/1.1 201 Created
Location: /exchange/v1.0/safeLinksPolicies/exonaut-audit-safelinks

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#safeLinksPolicies/$entity",
  "Id": "exonaut-audit-safelinks",
  "Name": "exonaut-audit-safelinks",
  "Identity": "exonaut-audit-safelinks",
  "AdminDisplayName": "",
  "Guid": "012a5a4f-5f5a-48c7-abcd-4ab3ddf273c7",
  "IsEnabled": false,
  "IsBuiltInProtection": false,
  "EnableSafeLinksForEmail": true,
  "EnableSafeLinksForTeams": true,
  "EnableSafeLinksForOffice": true,
  "ScanUrls": true,
  "DeliverMessageAfterScan": true,
  "EnableForInternalSenders": true,
  "TrackClicks": true,
  "AllowClickThrough": false,
  "DisableUrlRewrite": false,
  "EnableOrganizationBranding": false,
  "CustomNotificationText": "",
  "DoNotRewriteUrls": [],
  "WhenCreated": "2026-05-29T18:44:57+03:00",
  "WhenChanged": "2026-05-29T18:44:57+03:00",
  "CustomUrlList": [],
  "DistinguishedName": "CN=exonaut-audit-safelinks,CN=Safe Links,CN=Transport Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
  "ExchangeObjectId": "012a5a4f-5f5a-48c7-abcd-4ab3ddf273c7",
  "LocalizedNotificationTextList": [],
  "LocalizedUrlTextList": [],
  "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",
  "RecommendedPolicyType": "Custom",
  "WhenChangedUTC": "2026-05-29T15:44:57Z",
  "WhenCreatedUTC": "2026-05-29T15:44:57Z"
}

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

Get a single safeLinksPolicies entry by Identity.

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

Get a single Safe Links policy

Returns one Safe Links policy by identity, including its time-of-click protection settings. Backed by Get-SafeLinksPolicy with -Identity {key}.

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#safeLinksPolicies/$entity",
  "Id": "Built-In Protection Policy",
  "Name": "Built-In Protection Policy",
  "Identity": "Built-In Protection Policy",
  "AdminDisplayName": "",
  "Guid": "71a63616-9bbd-42fe-96da-2041b53db5f0",
  "IsEnabled": false,
  "IsBuiltInProtection": true,
  "EnableSafeLinksForEmail": true,
  "EnableSafeLinksForTeams": true,
  "EnableSafeLinksForOffice": true,
  "ScanUrls": true,
  "DeliverMessageAfterScan": true,
  "EnableForInternalSenders": false,
  "TrackClicks": true,
  "AllowClickThrough": true,
  "DisableUrlRewrite": true,
  "EnableOrganizationBranding": false,
  "CustomNotificationText": "",
  "DoNotRewriteUrls": [],
  "WhenCreated": "2026-03-30T17:42:16+03:00",
  "WhenChanged": "2026-03-30T17:42:26+03:00",
  "CustomUrlList": [],
  "DistinguishedName": "CN=Built-In Protection Policy,CN=Safe Links,CN=Transport Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
  "ExchangeObjectId": "d2065168-768f-4ec2-9e0e-e0bfda7d3186",
  "LocalizedNotificationTextList": [],
  "LocalizedUrlTextList": [],
  "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",
  "RecommendedPolicyType": "Custom",
  "WhenChangedUTC": "2026-03-30T14:42:26Z",
  "WhenCreatedUTC": "2026-03-30T14:42:16Z"
}

Notes: The {key} is the policy Name/Identity (e.g. “Built-In Protection Policy”); URL-encode spaces. A 404 is returned when the identity doesn’t resolve.

Get a single safeLinksPolicies entry - not found

Returns a 404 with the canonical error envelope when the requested Safe Links policy identity does not resolve to an existing object. Backed by Get-SafeLinksPolicy with -Identity {key}.

GET /exchange/v1.0/safeLinksPolicies/{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-SafeLinksPolicy"
    }
  },
  "correlationId": "0HNLSU6PPVJ03:00000001"
}

Notes: The identity is matched against the policy Name/Identity; an unknown value yields this NotFound envelope.

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

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

Parameter	In	Type
`adminDisplayName`	body
`allowClickThrough`	body
`customNotificationText`	body
`deliverMessageAfterScan`	body
`disableUrlRewrite`	body
`doNotRewriteUrls`	body
`enableForInternalSenders`	body
`enableOrganizationBranding`	body
`enableSafeLinksForEmail`	body
`enableSafeLinksForOffice`	body
`enableSafeLinksForTeams`	body
`scanUrls`	body
`trackClicks`	body
`useTranslatedNotificationText`	body
`dryRun`	query	bool (switch)

Update a Safe Links policy

Partially update an existing Safe Links policy via Set-SafeLinksPolicy. Only the body fields present are passed to the cmdlet; the post-Set entity is returned.

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

{
  "adminDisplayName": "EXONAUT sample Safe Links policy (updated)",
  "enableSafeLinksForEmail": true,
  "allowClickThrough": false
}

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

{
  "Id": "exonaut-sample-safeLinksPolicies",
  "Identity": "exonaut-sample-safeLinksPolicies",
  "Name": "exonaut-sample-safeLinksPolicies",
  "AdminDisplayName": "EXONAUT sample Safe Links policy (updated)",
  "EnableSafeLinksForEmail": true,
  "AllowClickThrough": false
}

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

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

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

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

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

Delete a safe links policy

Removes the safe links policy by Identity. Returns 204. Backed by Remove-SafeLinksPolicy.

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

HTTP/1.1 204 No Content

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