atpBuiltInProtectionRule

Built-in Protection Rule. Defender built-in preset protection, exceptions only. The atpBuiltInProtectionRule singleton lives under /exchange/v1.0/atpBuiltInProtectionRule in the Threat protection category.

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

Routes

Method	Path	Synopsis	Role	Plan
GET	`/exchange/v1.0/atpBuiltInProtectionRule`	Get the tenant-wide built-in protection rule for Defender Standard preset (singleton).	`ThreatPolicy.Read`	Community
POST	`/exchange/v1.0/atpBuiltInProtectionRule`	POST /atpBuiltInProtectionRule - provision-if-absent via New-ATPBuiltInProtectionRule. Required: safeAttachmentPolicy + safeLinksPolicy identities.	`ThreatPolicy.ReadWrite`	Enterprise
PATCH	`/exchange/v1.0/atpBuiltInProtectionRule`	Partial update via Set-ATPBuiltInProtectionRule (singleton - no URL key).	`ThreatPolicy.ReadWrite`	Enterprise

GET /exchange/v1.0/atpBuiltInProtectionRule

Get the tenant-wide built-in protection rule for Defender Standard preset (singleton).

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

Parameter	In	Type	Required	Description
`state`	query	string		Server-side filter by rule enablement state. One of: Enabled \| Disabled.

List atpBuiltInProtectionRule

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

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

HTTP/1.1 200 OK

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

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

POST /exchange/v1.0/atpBuiltInProtectionRule

POST /atpBuiltInProtectionRule - provision-if-absent via New-ATPBuiltInProtectionRule. Required: safeAttachmentPolicy + safeLinksPolicy identities.

Singleton entity (isSingleton: true; keyless GET + PATCH). The “Built-In Protection” preset is one-per-tenant; the POST is kept as a provision-if-absent action to (re)create the built-in rule when the tenant has none. Callers normally PATCH (Set), not POST. (Audit 2026-06-01 RS-1 - owner decision: keep the POST.)

Backing cmdlet: New-ATPBuiltInProtectionRule. Role: ThreatPolicy.ReadWrite (Enterprise).

Parameter	In	Type	Required
`safeAttachmentPolicy`	body		yes
`safeLinksPolicy`	body		yes
`comments`	body
`exceptIfRecipientDomainIs`	body
`exceptIfSentTo`	body
`exceptIfSentToMemberOf`	body
`name`	body
`dryRun`	query	bool (switch)

Create rejected when a required policy identity is missing

New-ATPBuiltInProtectionRule requires both safeAttachmentPolicy and safeLinksPolicy. Omitting safeLinksPolicy fails validation before the cmdlet runs and returns the canonical 400 envelope.

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

{
  "name": "exonaut-sample-atpBuiltInProtectionRule",
  "safeAttachmentPolicy": "Built-In Protection Policy"
}

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

{
  "error": {
    "code": "BadRequest",
    "message": "The 'safeLinksPolicy' field is required.",
    "target": "safeLinksPolicy"
  },
  "correlationId": "0HN7Q2K9F3ABC:00000007"
}

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

Create the built-in protection rule for Defender’s Standard preset

Creates the tenant’s built-in (Standard preset) protection rule via New-ATPBuiltInProtectionRule. Requires the SafeAttachmentPolicy and SafeLinksPolicy identities; optional recipient-domain and recipient exceptions scope the rule.

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

{
  "name": "exonaut-sample-atpBuiltInProtectionRule",
  "safeAttachmentPolicy": "Built-In Protection Policy",
  "safeLinksPolicy": "Built-In Protection Policy",
  "comments": "Managed by Exonaut sample automation.",
  "exceptIfRecipientDomainIs": [
    "contoso.com"
  ],
  "exceptIfSentTo": [
    "[email protected]"
  ]
}

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

{
  "Id": "exonaut-sample-atpBuiltInProtectionRule",
  "Identity": "exonaut-sample-atpBuiltInProtectionRule",
  "Name": "exonaut-sample-atpBuiltInProtectionRule",
  "SafeAttachmentPolicy": "Built-In Protection Policy",
  "SafeLinksPolicy": "Built-In Protection Policy",
  "Comments": "Managed by Exonaut sample automation.",
  "ExceptIfRecipientDomainIs": [
    "contoso.com"
  ],
  "ExceptIfSentTo": [
    "[email protected]"
  ]
}

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

PATCH /exchange/v1.0/atpBuiltInProtectionRule

Partial update via Set-ATPBuiltInProtectionRule (singleton - no URL key).

Backing cmdlet: Set-ATPBuiltInProtectionRule. Role: ThreatPolicy.ReadWrite (Enterprise).

Parameter	In	Type
`comments`	body
`exceptIfRecipientDomainIs`	body
`exceptIfSentTo`	body
`exceptIfSentToMemberOf`	body
`dryRun`	query	bool (switch)

Update the built-in protection rule’s comments and exceptions

Partially updates the tenant’s built-in protection rule via Set-ATPBuiltInProtectionRule. This is a singleton, so no URL key is supplied; only the SetWritable fields (comments and recipient exceptions) may change.

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

{
  "comments": "Updated by Exonaut sample automation.",
  "exceptIfRecipientDomainIs": [
    "contoso.com"
  ],
  "exceptIfSentTo": [
    "[email protected]"
  ]
}

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

{
  "Id": "exonaut-sample-atpBuiltInProtectionRule",
  "Identity": "exonaut-sample-atpBuiltInProtectionRule",
  "Name": "exonaut-sample-atpBuiltInProtectionRule",
  "Comments": "Updated by Exonaut sample automation.",
  "ExceptIfRecipientDomainIs": [
    "contoso.com"
  ],
  "ExceptIfSentTo": [
    "[email protected]"
  ]
}

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

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