Skip to content
exonaut

antiPhishPolicies

Anti-Phishing Policies. Defender impersonation and spoof protection policies. The antiPhishPolicies entity set lives under /exchange/v1.0/antiPhishPolicies in the Threat protection category.

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

Routes

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

GET /exchange/v1.0/antiPhishPolicies

Section titled “GET /exchange/v1.0/antiPhishPolicies”

List antiPhishPolicies entries.

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

List antiPhishPolicies

Section titled “List antiPhishPolicies”

Returns the anti-phishing policies configured in the organization, including the built-in default and any custom policies. Backed by the Get-AntiPhishPolicy cmdlet.

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


{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#antiPhishPolicies",
  "value": [
    {
      "Id": "Office365 AntiPhish Default",
      "Name": "Office365 AntiPhish Default",
      "Identity": "Office365 AntiPhish Default",
      "AdminDisplayName": "",
      "Guid": "bed0e3e2-a966-4e78-ba10-7625ec4b97f2",
      "Enabled": true,
      "IsDefault": true,
      "EnableMailboxIntelligence": true,
      "EnableMailboxIntelligenceProtection": true,
      "EnableSpoofIntelligence": true,
      "EnableFirstContactSafetyTips": true,
      "EnableSimilarUsersSafetyTips": true,
      "EnableSimilarDomainsSafetyTips": true,
      "EnableUnusualCharactersSafetyTips": true,
      "EnableUnauthenticatedSender": true,
      "EnableViaTag": true,
      "PhishThresholdLevel": "3",
      "AuthenticationFailAction": "Quarantine",
      "SpoofQuarantineTag": "DefaultFullAccessWithNotificationPolicy",
      "MailboxIntelligenceQuarantineTag": "DefaultFullAccessWithNotificationPolicy",
      "TargetedDomainProtectionAction": "Quarantine",
      "TargetedUserProtectionAction": "NoAction",
      "TargetedUsersToProtect": [],
      "TargetedDomainsToProtect": [],
      "ExcludedSenders": [
        "ayla.kol@contoso.com"
      ],
      "ExcludedDomains": [],
      "WhenCreated": "2026-03-30T17:42:10+03:00",
      "WhenChanged": "2026-03-30T17:42:17+03:00",
      "DistinguishedName": "CN=Office365 AntiPhish Default,CN=AntiPhish,CN=Transport Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
      "DmarcQuarantineAction": "Quarantine",
      "DmarcRejectAction": "Reject",
      "EnableOrganizationDomainsProtection": true,
      "EnableSuspiciousSafetyTip": false,
      "EnableTargetedDomainsProtection": false,
      "EnableTargetedUserProtection": false,
      "ExchangeObjectId": "eac34944-7f68-4371-b3c5-8d7fa7fcf6c9",
      "ExcludedSubDomains": [],
      "HonorDmarcPolicy": true,
      "ImpersonationProtectionState": "Manual",
      "MailboxIntelligenceProtectionAction": "Quarantine",
      "MailboxIntelligenceProtectionActionRecipients": [],
      "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",
      "PolicyTag": "",
      "RecommendedPolicyType": "Custom",
      "TargetedDomainActionRecipients": [],
      "TargetedDomainQuarantineTag": "DefaultFullAccessWithNotificationPolicy",
      "TargetedUserActionRecipients": [],
      "TargetedUserQuarantineTag": "DefaultFullAccessPolicy",
      "WhenChangedUTC": "2026-03-30T14:42:17Z",
      "WhenCreatedUTC": "2026-03-30T14:42:10Z"
    },
    {
      "Id": "Test",
      "Name": "Test",
      "Identity": "Test",
      "AdminDisplayName": "",
      "Guid": "ca220df3-15f2-4fa6-92f1-3777222853d4",
      "Enabled": true,
      "IsDefault": false,
      "EnableMailboxIntelligence": true,
      "EnableMailboxIntelligenceProtection": true,
      "EnableSpoofIntelligence": true,
      "EnableFirstContactSafetyTips": false,
      "EnableSimilarUsersSafetyTips": false,
      "EnableSimilarDomainsSafetyTips": false,
      "EnableUnusualCharactersSafetyTips": false,
      "EnableUnauthenticatedSender": true,
      "EnableViaTag": true,
      "PhishThresholdLevel": "1",
      "AuthenticationFailAction": "MoveToJmf",
      "SpoofQuarantineTag": "DefaultFullAccessPolicy",
      "MailboxIntelligenceQuarantineTag": "DefaultFullAccessPolicy",
      "TargetedDomainProtectionAction": "NoAction",
      "TargetedUserProtectionAction": "Quarantine",
      "TargetedUsersToProtect": [
        "Ayla Kol;ayla.kol@contoso.com",
        "CEO@example.com;ceo@example.com"
      ],
      "TargetedDomainsToProtect": [
        "example.com"
      ],
      "ExcludedSenders": [],
      "ExcludedDomains": [],
      "WhenCreated": "2026-03-31T17:39:59+03:00",
      "WhenChanged": "2026-03-31T17:40:10+03:00",
      "DistinguishedName": "CN=Test,CN=AntiPhish,CN=Transport Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
      "DmarcQuarantineAction": "Quarantine",
      "DmarcRejectAction": "Reject",
      "EnableOrganizationDomainsProtection": false,
      "EnableSuspiciousSafetyTip": false,
      "EnableTargetedDomainsProtection": true,
      "EnableTargetedUserProtection": true,
      "ExchangeObjectId": "4be92d57-8548-46c0-9d4c-52ac76d35dd2",
      "ExcludedSubDomains": [],
      "HonorDmarcPolicy": true,
      "ImpersonationProtectionState": "Manual",
      "MailboxIntelligenceProtectionAction": "NoAction",
      "MailboxIntelligenceProtectionActionRecipients": [],
      "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",
      "PolicyTag": "",
      "RecommendedPolicyType": "Custom",
      "TargetedDomainActionRecipients": [],
      "TargetedDomainQuarantineTag": "DefaultFullAccessPolicy",
      "TargetedUserActionRecipients": [],
      "TargetedUserQuarantineTag": "DefaultFullAccessPolicy",
      "WhenChangedUTC": "2026-03-31T14:40:10Z",
      "WhenCreatedUTC": "2026-03-31T14:39:59Z"
    }
  ]
}

Notes: The default policy (Office365 AntiPhish Default) always exists and has IsDefault=true; custom policies have IsDefault=false and are scoped via an associated anti-phish rule.

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

POST /exchange/v1.0/antiPhishPolicies

Section titled “POST /exchange/v1.0/antiPhishPolicies”

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

Parameter In Type Required Description
name body yes
adminDisplayName body
authenticationFailAction body
dmarcQuarantineAction body
dmarcRejectAction body
enabled body
enableFirstContactSafetyTips body
enableMailboxIntelligence body
enableMailboxIntelligenceProtection body
enableOrganizationDomainsProtection body
enableSimilarDomainsSafetyTips body
enableSimilarUsersSafetyTips body
enableSpoofIntelligence body
enableTargetedDomainsProtection body
enableTargetedUserProtection body
enableUnauthenticatedSender body
enableUnusualCharactersSafetyTips body
enableViaTag body
excludedDomains body
excludedSenders body
honorDmarcPolicy body
impersonationProtectionState body
mailboxIntelligenceProtectionAction body
mailboxIntelligenceProtectionActionRecipients body
mailboxIntelligenceQuarantineTag body
phishThresholdLevel body
policyTag body
similarUsersSafetyTipsCustomText body
spoofQuarantineTag body
targetedDomainActionRecipients body
targetedDomainProtectionAction body
targetedDomainQuarantineTag body
targetedDomainsToProtect body
targetedUserActionRecipients body
targetedUserProtectionAction body
targetedUserQuarantineTag body
targetedUsersToProtect body
unusualCharactersSafetyTipsCustomText body
dryRun query bool (switch)

Create antiPhishPolicies - duplicate name (409)

Section titled “Create antiPhishPolicies - duplicate name (409)”

Anti-phishing policy create fails with 409 when a policy of that name already exists. Backed by New-AntiPhishPolicy.

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


{
  "name": "exonaut-audit-antiphish"
}
HTTP/1.1 409 Conflict


{
  "error": {
    "code": "Conflict",
    "message": "Cmdlet 'New-AntiPhishPolicy' failed: ||Anti phish policy 'exonaut-audit-antiphish' already exists.",
    "target": null,
    "innerError": {
      "cmdlet": "New-AntiPhishPolicy"
    }
  },
  "correlationId": "0HNLTIGH3TLO1:00000001"
}

Create a antiPhishPolicie

Section titled “Create a antiPhishPolicie”

Anti-phishing policy create. Required: name. Returns 201 + Location + the freshly-fetched policy. Backed by New-AntiPhishPolicy.

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


{
  "name": "exonaut-audit-antiphish"
}
HTTP/1.1 201 Created
Location: /exchange/v1.0/antiPhishPolicies/exonaut-audit-antiphish


{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#antiPhishPolicies/$entity",
  "Id": "exonaut-audit-antiphish",
  "Name": "exonaut-audit-antiphish",
  "Identity": "exonaut-audit-antiphish",
  "AdminDisplayName": "",
  "Guid": "f5537bd5-a410-4527-a7b1-04a8faf08693",
  "Enabled": true,
  "IsDefault": false,
  "EnableMailboxIntelligence": true,
  "EnableMailboxIntelligenceProtection": false,
  "EnableSpoofIntelligence": true,
  "EnableFirstContactSafetyTips": false,
  "EnableSimilarUsersSafetyTips": false,
  "EnableSimilarDomainsSafetyTips": false,
  "EnableUnusualCharactersSafetyTips": false,
  "EnableUnauthenticatedSender": true,
  "EnableViaTag": true,
  "PhishThresholdLevel": "1",
  "AuthenticationFailAction": "MoveToJmf",
  "SpoofQuarantineTag": "DefaultFullAccessPolicy",
  "MailboxIntelligenceQuarantineTag": "DefaultFullAccessPolicy",
  "TargetedDomainProtectionAction": "NoAction",
  "TargetedUserProtectionAction": "NoAction",
  "TargetedUsersToProtect": [],
  "TargetedDomainsToProtect": [],
  "ExcludedSenders": [],
  "ExcludedDomains": [],
  "WhenCreated": "2026-05-29T18:34:44+03:00",
  "WhenChanged": "2026-05-29T18:34:44+03:00",
  "DistinguishedName": "CN=exonaut-audit-antiphish,CN=AntiPhish,CN=Transport Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
  "DmarcQuarantineAction": "Quarantine",
  "DmarcRejectAction": "Reject",
  "EnableOrganizationDomainsProtection": false,
  "EnableSuspiciousSafetyTip": false,
  "EnableTargetedDomainsProtection": false,
  "EnableTargetedUserProtection": false,
  "ExchangeObjectId": "f5537bd5-a410-4527-a7b1-04a8faf08693",
  "ExcludedSubDomains": [],
  "HonorDmarcPolicy": true,
  "ImpersonationProtectionState": "Manual",
  "MailboxIntelligenceProtectionAction": "NoAction",
  "MailboxIntelligenceProtectionActionRecipients": [],
  "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",
  "PolicyTag": "",
  "RecommendedPolicyType": "Custom",
  "TargetedDomainActionRecipients": [],
  "TargetedDomainQuarantineTag": "DefaultFullAccessPolicy",
  "TargetedUserActionRecipients": [],
  "TargetedUserQuarantineTag": "DefaultFullAccessPolicy",
  "WhenChangedUTC": "2026-05-29T15:34:44Z",
  "WhenCreatedUTC": "2026-05-29T15:34:44Z"
}

Related: GET /exchange/v1.0/antiPhishPolicies, DELETE /exchange/v1.0/antiPhishPolicies/{key}

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

Section titled “GET /exchange/v1.0/antiPhishPolicies/{key}”

Get a single antiPhishPolicies entry by Identity.

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

Get a single antiPhishPolicies entry

Section titled “Get a single antiPhishPolicies entry”

Returns the full anti-phishing policy identified by {key} (its Name/Identity). Backed by Get-AntiPhishPolicy with -Identity {key}.

GET /exchange/v1.0/antiPhishPolicies/{key} HTTP/1.1
Authorization: Bearer {token}
HTTP/1.1 200 OK


{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#antiPhishPolicies/$entity",
  "Id": "Office365 AntiPhish Default",
  "Name": "Office365 AntiPhish Default",
  "Identity": "Office365 AntiPhish Default",
  "AdminDisplayName": "",
  "Guid": "bed0e3e2-a966-4e78-ba10-7625ec4b97f2",
  "Enabled": true,
  "IsDefault": true,
  "EnableMailboxIntelligence": true,
  "EnableMailboxIntelligenceProtection": true,
  "EnableSpoofIntelligence": true,
  "EnableFirstContactSafetyTips": true,
  "EnableSimilarUsersSafetyTips": true,
  "EnableSimilarDomainsSafetyTips": true,
  "EnableUnusualCharactersSafetyTips": true,
  "EnableUnauthenticatedSender": true,
  "EnableViaTag": true,
  "PhishThresholdLevel": "3",
  "AuthenticationFailAction": "Quarantine",
  "SpoofQuarantineTag": "DefaultFullAccessWithNotificationPolicy",
  "MailboxIntelligenceQuarantineTag": "DefaultFullAccessWithNotificationPolicy",
  "TargetedDomainProtectionAction": "Quarantine",
  "TargetedUserProtectionAction": "NoAction",
  "TargetedUsersToProtect": [],
  "TargetedDomainsToProtect": [],
  "ExcludedSenders": [
    "ayla.kol@contoso.com"
  ],
  "ExcludedDomains": [],
  "WhenCreated": "2026-03-30T17:42:10+03:00",
  "WhenChanged": "2026-03-30T17:42:17+03:00",
  "DistinguishedName": "CN=Office365 AntiPhish Default,CN=AntiPhish,CN=Transport Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
  "DmarcQuarantineAction": "Quarantine",
  "DmarcRejectAction": "Reject",
  "EnableOrganizationDomainsProtection": true,
  "EnableSuspiciousSafetyTip": false,
  "EnableTargetedDomainsProtection": false,
  "EnableTargetedUserProtection": false,
  "ExchangeObjectId": "eac34944-7f68-4371-b3c5-8d7fa7fcf6c9",
  "ExcludedSubDomains": [],
  "HonorDmarcPolicy": true,
  "ImpersonationProtectionState": "Manual",
  "MailboxIntelligenceProtectionAction": "Quarantine",
  "MailboxIntelligenceProtectionActionRecipients": [],
  "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",
  "PolicyTag": "",
  "RecommendedPolicyType": "Custom",
  "TargetedDomainActionRecipients": [],
  "TargetedDomainQuarantineTag": "DefaultFullAccessWithNotificationPolicy",
  "TargetedUserActionRecipients": [],
  "TargetedUserQuarantineTag": "DefaultFullAccessPolicy",
  "WhenChangedUTC": "2026-03-30T14:42:17Z",
  "WhenCreatedUTC": "2026-03-30T14:42:10Z"
}

Notes: The {key} is the policy Name/Identity (e.g. “Office365 AntiPhish Default”); URL-encode spaces. Returns 404 if the identity doesn’t resolve.

Related: GET /exchange/v1.0/antiPhishPolicies

Get a single antiPhishPolicies entry - not found

Section titled “Get a single antiPhishPolicies entry - not found”

Returns a 404 with the canonical error envelope when the supplied {key} does not resolve to an existing anti-phishing policy. Backed by Get-AntiPhishPolicy with -Identity {key}.

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

Notes: The {key} is the policy Name/Identity; an unrecognized value yields this NotFound envelope rather than an empty body.

Related: GET /exchange/v1.0/antiPhishPolicies

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

Section titled “PATCH /exchange/v1.0/antiPhishPolicies/{key}”

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

Parameter In Type Required Description
adminDisplayName body
authenticationFailAction body
dmarcQuarantineAction body
dmarcRejectAction body
enabled body
enableFirstContactSafetyTips body
enableMailboxIntelligence body
enableMailboxIntelligenceProtection body
enableOrganizationDomainsProtection body
enableSimilarDomainsSafetyTips body
enableSimilarUsersSafetyTips body
enableSpoofIntelligence body
enableTargetedDomainsProtection body
enableTargetedUserProtection body
enableUnauthenticatedSender body
enableUnusualCharactersSafetyTips body
enableViaTag body
excludedDomains body
excludedSenders body
honorDmarcPolicy body
impersonationProtectionState body
mailboxIntelligenceProtectionAction body
mailboxIntelligenceProtectionActionRecipients body
mailboxIntelligenceQuarantineTag body
makeDefault body boolean (switch)
phishThresholdLevel body
policyTag body
spoofQuarantineTag body
targetedDomainActionRecipients body
targetedDomainProtectionAction body
targetedDomainQuarantineTag body
targetedDomainsToProtect body
targetedUserActionRecipients body
targetedUserProtectionAction body
targetedUserQuarantineTag body
targetedUsersToProtect body
dryRun query bool (switch)

Update an anti-phishing policy

Section titled “Update an anti-phishing policy”

Partial update of an anti-phishing policy via Set-AntiPhishPolicy. Only the body fields present are passed to the cmdlet; returns 200 plus the post-Set entity.

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


{
  "adminDisplayName": "EXONAUT sample anti-phish policy",
  "enabled": true,
  "phishThresholdLevel": 2
}
HTTP/1.1 200 OK
Content-Type: application/json


{
  "Id": "exonaut-sample-antiPhishPolicies",
  "Identity": "exonaut-sample-antiPhishPolicies",
  "Name": "exonaut-sample-antiPhishPolicies",
  "AdminDisplayName": "EXONAUT sample anti-phish policy",
  "Enabled": true,
  "PhishThresholdLevel": 2
}

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

Related: GET /exchange/v1.0/antiPhishPolicies

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

Section titled “DELETE /exchange/v1.0/antiPhishPolicies/{key}”

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

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

Parameter In Type Required Description
dryRun query bool (switch)

Delete a antiPhishPolicie

Section titled “Delete a antiPhishPolicie”

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

DELETE /exchange/v1.0/antiPhishPolicies/{key} HTTP/1.1
Authorization: Bearer {token}
HTTP/1.1 204 No Content

Related: POST /exchange/v1.0/antiPhishPolicies, GET /exchange/v1.0/antiPhishPolicies/{key}

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