malwareFilterPolicies

Malware Filter Policies. Policies that block or quarantine messages carrying malware. The malwareFilterPolicies entity set lives under /exchange/v1.0/malwareFilterPolicies in the Threat protection category.

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

Routes

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

GET /exchange/v1.0/malwareFilterPolicies

List malwareFilterPolicies entries.

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

List malware filter policies

Returns the tenant’s malware filter policies, including the built-in Default policy and any custom ones. Backed by the Get-MalwareFilterPolicy cmdlet.

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#malwareFilterPolicies",
  "value": [
    {
      "Id": "Default",
      "Name": "Default",
      "Identity": "Default",
      "AdminDisplayName": "",
      "Guid": "32edb62b-8108-4cdb-a65c-9b0af063fd80",
      "IsDefault": true,
      "Action": null,
      "FileTypes": [
        "ace",
        "apk",
        "app",
        "appx",
        "ani",
        "arj",
        "bat",
        "cab",
        "cmd",
        "com",
        "deb",
        "dex",
        "dll",
        "docm",
        "elf",
        "exe",
        "hta",
        "img",
        "iso",
        "jar",
        "jnlp",
        "kext",
        "lha",
        "lib",
        "library",
        "lnk",
        "lzh",
        "macho",
        "msc",
        "msi",
        "msix",
        "msp",
        "mst",
        "pif",
        "ppa",
        "ppam",
        "reg",
        "rev",
        "scf",
        "scr",
        "sct",
        "sys",
        "uif",
        "vb",
        "vbe",
        "vbs",
        "vxd",
        "wsc",
        "wsf",
        "wsh",
        "xll",
        "xz",
        "z"
      ],
      "EnableFileFilter": true,
      "ZapEnabled": true,
      "EnableInternalSenderAdminNotifications": true,
      "InternalSenderAdminAddress": "SecOps@contoso.com",
      "EnableExternalSenderAdminNotifications": false,
      "ExternalSenderAdminAddress": "SecOps@contoso.com",
      "QuarantineTag": "AdminOnlyAccessPolicy",
      "CustomNotifications": "False",
      "WhenCreated": "2026-03-30T17:42:05+03:00",
      "WhenChanged": "2026-03-30T17:42:08+03:00",
      "CustomExternalBody": "",
      "CustomExternalSubject": "",
      "CustomFromAddress": "",
      "CustomFromName": "",
      "CustomInternalBody": "",
      "CustomInternalSubject": "",
      "DistinguishedName": "CN=Default,CN=Malware Filter,CN=Transport Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
      "ExchangeObjectId": "f26b1867-aedc-4a6c-b599-52ae8fcdb471",
      "FileTypeAction": "Quarantine",
      "IsPolicyOverrideApplied": 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",
      "RecommendedPolicyType": "Custom",
      "WhenChangedUTC": "2026-03-30T14:42:08Z",
      "WhenCreatedUTC": "2026-03-30T14:42:05Z"
    }
  ]
}

Notes: The Default policy is always present and cannot be removed; its IsDefault flag is true. FileTypes lists the extensions blocked by the common attachments filter when EnableFileFilter is true.

POST /exchange/v1.0/malwareFilterPolicies

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

Parameter	In	Type	Required
`name`	body		yes
`adminDisplayName`	body
`customExternalBody`	body
`customExternalSubject`	body
`customFromAddress`	body
`customFromName`	body
`customInternalBody`	body
`customInternalSubject`	body
`customNotifications`	body
`enableExternalSenderAdminNotifications`	body
`enableFileFilter`	body
`enableInternalSenderAdminNotifications`	body
`externalSenderAdminAddress`	body
`fileTypeAction`	body
`fileTypes`	body
`internalSenderAdminAddress`	body
`quarantineTag`	body
`zapEnabled`	body
`dryRun`	query	bool (switch)

Create malwareFilterPolicies - duplicate name (409)

Malware filter policy create fails with 409 when a policy of that name already exists. Backed by New-MalwareFilterPolicy.

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

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

HTTP/1.1 409 Conflict

{
  "error": {
    "code": "Conflict",
    "message": "Cmdlet 'New-MalwareFilterPolicy' failed: ||Active Directory operation failed on VI1PR01A17DC001.EURPR01A017.PROD.OUTLOOK.COM. The object 'CN=exonaut-audit-malware,CN=Malware Filter,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-MalwareFilterPolicy"
    }
  },
  "correlationId": "0HNLTIGH3TLO9:00000001"
}

Create a malwareFilterPolicie

Malware filter policy create. Required: name. Returns 201 + Location + the freshly-fetched policy. Backed by New-MalwareFilterPolicy.

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

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

HTTP/1.1 201 Created
Location: /exchange/v1.0/malwareFilterPolicies/exonaut-audit-malware

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#malwareFilterPolicies/$entity",
  "Id": "exonaut-audit-malware",
  "Name": "exonaut-audit-malware",
  "Identity": "exonaut-audit-malware",
  "AdminDisplayName": "",
  "Guid": "78764bc9-f944-4454-aecf-e34ec25c2a1e",
  "IsDefault": false,
  "Action": null,
  "FileTypes": [
    "ace",
    "apk",
    "app",
    "appx",
    "ani",
    "arj",
    "bat",
    "cab",
    "cmd",
    "com",
    "deb",
    "dex",
    "dll",
    "docm",
    "elf",
    "exe",
    "hta",
    "img",
    "iso",
    "jar",
    "jnlp",
    "kext",
    "lha",
    "lib",
    "library",
    "lnk",
    "lzh",
    "macho",
    "msc",
    "msi",
    "msix",
    "msp",
    "mst",
    "pif",
    "ppa",
    "ppam",
    "reg",
    "rev",
    "scf",
    "scr",
    "sct",
    "sys",
    "uif",
    "vb",
    "vbe",
    "vbs",
    "vxd",
    "wsc",
    "wsf",
    "wsh",
    "xll",
    "xz",
    "z"
  ],
  "EnableFileFilter": true,
  "ZapEnabled": true,
  "EnableInternalSenderAdminNotifications": false,
  "InternalSenderAdminAddress": "",
  "EnableExternalSenderAdminNotifications": false,
  "ExternalSenderAdminAddress": "",
  "QuarantineTag": "AdminOnlyAccessPolicy",
  "CustomNotifications": "False",
  "WhenCreated": "2026-05-29T18:34:49+03:00",
  "WhenChanged": "2026-05-29T18:34:49+03:00",
  "CustomExternalBody": "",
  "CustomExternalSubject": "",
  "CustomFromAddress": "",
  "CustomFromName": "",
  "CustomInternalBody": "",
  "CustomInternalSubject": "",
  "DistinguishedName": "CN=exonaut-audit-malware,CN=Malware Filter,CN=Transport Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
  "ExchangeObjectId": "78764bc9-f944-4454-aecf-e34ec25c2a1e",
  "FileTypeAction": "Reject",
  "IsPolicyOverrideApplied": 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",
  "RecommendedPolicyType": "Custom",
  "WhenChangedUTC": "2026-05-29T15:34:49Z",
  "WhenCreatedUTC": "2026-05-29T15:34:49Z"
}

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

Get a single malwareFilterPolicies entry by Identity.

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

Get a single malware filter policy

Returns one malware filter policy resolved by its identity (here, the built-in Default policy). Backed by Get-MalwareFilterPolicy with -Identity {key}.

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#malwareFilterPolicies/$entity",
  "Id": "Default",
  "Name": "Default",
  "Identity": "Default",
  "AdminDisplayName": "",
  "Guid": "32edb62b-8108-4cdb-a65c-9b0af063fd80",
  "IsDefault": true,
  "Action": null,
  "FileTypes": [
    "ace",
    "apk",
    "app",
    "appx",
    "ani",
    "arj",
    "bat",
    "cab",
    "cmd",
    "com",
    "deb",
    "dex",
    "dll",
    "docm",
    "elf",
    "exe",
    "hta",
    "img",
    "iso",
    "jar",
    "jnlp",
    "kext",
    "lha",
    "lib",
    "library",
    "lnk",
    "lzh",
    "macho",
    "msc",
    "msi",
    "msix",
    "msp",
    "mst",
    "pif",
    "ppa",
    "ppam",
    "reg",
    "rev",
    "scf",
    "scr",
    "sct",
    "sys",
    "uif",
    "vb",
    "vbe",
    "vbs",
    "vxd",
    "wsc",
    "wsf",
    "wsh",
    "xll",
    "xz",
    "z"
  ],
  "EnableFileFilter": true,
  "ZapEnabled": true,
  "EnableInternalSenderAdminNotifications": true,
  "InternalSenderAdminAddress": "SecOps@contoso.com",
  "EnableExternalSenderAdminNotifications": false,
  "ExternalSenderAdminAddress": "SecOps@contoso.com",
  "QuarantineTag": "AdminOnlyAccessPolicy",
  "CustomNotifications": "False",
  "WhenCreated": "2026-03-30T17:42:05+03:00",
  "WhenChanged": "2026-03-30T17:42:08+03:00",
  "CustomExternalBody": "",
  "CustomExternalSubject": "",
  "CustomFromAddress": "",
  "CustomFromName": "",
  "CustomInternalBody": "",
  "CustomInternalSubject": "",
  "DistinguishedName": "CN=Default,CN=Malware Filter,CN=Transport Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
  "ExchangeObjectId": "f26b1867-aedc-4a6c-b599-52ae8fcdb471",
  "FileTypeAction": "Quarantine",
  "IsPolicyOverrideApplied": 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",
  "RecommendedPolicyType": "Custom",
  "WhenChangedUTC": "2026-03-30T14:42:08Z",
  "WhenCreatedUTC": "2026-03-30T14:42:05Z"
}

Notes: The {key} is the policy Identity (e.g. Default). The Default policy is built-in and reported with IsDefault true.

Get a single malwareFilterPolicies entry - not found

When the supplied identity does not resolve to any malware filter policy, the API returns a 404 with the canonical error envelope. Backed by Get-MalwareFilterPolicy with -Identity {key}.

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

Notes: The identity is matched against the policy Name/Identity; a value that resolves to no policy yields this 404 envelope.

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

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

Parameter	In	Type
`adminDisplayName`	body
`customExternalBody`	body
`customExternalSubject`	body
`customFromAddress`	body
`customFromName`	body
`customInternalBody`	body
`customInternalSubject`	body
`customNotifications`	body
`enableExternalSenderAdminNotifications`	body
`enableFileFilter`	body
`enableInternalSenderAdminNotifications`	body
`externalSenderAdminAddress`	body
`fileTypeAction`	body
`fileTypes`	body
`internalSenderAdminAddress`	body
`isPolicyOverrideApplied`	body
`makeDefault`	body	boolean (switch)
`quarantineTag`	body
`zapEnabled`	body
`dryRun`	query	bool (switch)

Update a malware filter policy

Partial update of the malware filter policy at /malwareFilterPolicies/{key}. Only body fields present are passed to Set-MalwareFilterPolicy. Returns 200 + the post-Set entity (rename-aware re-fetch when name is in the body).

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

{
  "adminDisplayName": "Exonaut sample malware filter policy",
  "zapEnabled": true,
  "enableInternalSenderAdminNotifications": true
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#malwareFilterPolicies/$entity",
  "Id": "exonaut-sample-malwareFilterPolicies",
  "Name": "exonaut-sample-malwareFilterPolicies",
  "Identity": "exonaut-sample-malwareFilterPolicies",
  "AdminDisplayName": "Exonaut sample malware filter policy",
  "ZapEnabled": true,
  "EnableInternalSenderAdminNotifications": true,
  "InternalSenderAdminAddress": "",
  "EnableExternalSenderAdminNotifications": false,
  "ExternalSenderAdminAddress": "",
  "EnableFileFilter": true,
  "FileTypeAction": "Reject",
  "QuarantineTag": "AdminOnlyAccessPolicy",
  "CustomNotifications": "False",
  "IsDefault": false,
  "IsPolicyOverrideApplied": false,
  "RecommendedPolicyType": "Custom"
}

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

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

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

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

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

Delete a malwareFilterPolicie

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

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

HTTP/1.1 204 No Content

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