hostedOutboundSpamFilterPolicies

Outbound Spam Policies. Outbound spam filtering and message sending-limit policies. The hostedOutboundSpamFilterPolicies entity set lives under /exchange/v1.0/hostedOutboundSpamFilterPolicies in the Threat protection category.

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

Routes

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

GET /exchange/v1.0/hostedOutboundSpamFilterPolicies

List hostedOutboundSpamFilterPolicies entries.

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

List hostedOutboundSpamFilterPolicies

Returns the tenant’s outbound spam filter policies, which cap outbound recipient rates and configure suspicious-mail BCC/notification behavior. Backed by the Get-HostedOutboundSpamFilterPolicy cmdlet.

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#hostedOutboundSpamFilterPolicies",
  "value": [
    {
      "Id": "Default",
      "Name": "Default",
      "Identity": "Default",
      "AdminDisplayName": "",
      "Guid": "8da3edf2-39f0-490c-a5b4-ffe67c7a38a1",
      "IsDefault": true,
      "RecipientLimitExternalPerHour": 200,
      "RecipientLimitInternalPerHour": 200,
      "RecipientLimitPerDay": 1000,
      "ActionWhenThresholdReached": "BlockUser",
      "AutoForwardingMode": false,
      "NotifyOutboundSpamRecipients": [
        "[email protected]"
      ],
      "NotifyOutboundSpam": true,
      "WhenCreated": "2026-03-30T17:42:00+03:00",
      "WhenChanged": "2026-03-30T17:42:08+03:00",
      "BccSuspiciousOutboundAdditionalRecipients": [
        "[email protected]"
      ],
      "BccSuspiciousOutboundMail": true,
      "ConfigurationType": "HostedOutboundSpamFilterPolicy",
      "DistinguishedName": "CN=Default,CN=Outbound Spam Filter,CN=Transport Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
      "Enabled": false,
      "ExchangeObjectId": "bc3ac7f5-3306-4094-b9c6-9b2e079e3e6a",
      "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:00Z"
    }
  ]
}

Notes: Most tenants carry a single ‘Default’ policy; additional custom policies appear here once created via New-HostedOutboundSpamFilterPolicy.

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

POST /exchange/v1.0/hostedOutboundSpamFilterPolicies

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

Parameter	In	Type	Required	Description
name	body		yes
actionWhenThresholdReached	body
adminDisplayName	body
autoForwardingMode	body
bccSuspiciousOutboundAdditionalRecipients	body
bccSuspiciousOutboundMail	body
notifyOutboundSpam	body
notifyOutboundSpamRecipients	body
recipientLimitExternalPerHour	body
recipientLimitInternalPerHour	body
recipientLimitPerDay	body
dryRun	query	bool (switch)

Create outbound spam filter policy - duplicate (409)

Outbound spam filter policy create returns 409 when an object of that name already exists. Backed by New-HostedOutboundSpamFilterPolicy.

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

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

HTTP/1.1 409 Conflict

{
  "error": {
    "code": "Conflict",
    "message": "Cmdlet 'New-HostedOutboundSpamFilterPolicy' failed: ||Hosted outbound spam policy 'exonaut-audit-hosf' already exists.",
    "target": null,
    "innerError": {
      "cmdlet": "New-HostedOutboundSpamFilterPolicy"
    }
  },
  "correlationId": "0HNLTJ0Q1D323:00000001"
}

Create a outbound spam filter policy

Outbound spam filter policy create. Returns 201 + Location + the freshly-fetched object. Backed by New-HostedOutboundSpamFilterPolicy.

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

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

HTTP/1.1 201 Created
Location: /exchange/v1.0/hostedOutboundSpamFilterPolicies/exonaut-audit-hosf

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#hostedOutboundSpamFilterPolicies/$entity",
  "Id": "exonaut-audit-hosf",
  "Name": "exonaut-audit-hosf",
  "Identity": "exonaut-audit-hosf",
  "AdminDisplayName": "",
  "Guid": "0f044e81-d7f8-46d9-8489-e3a7e9fdaa57",
  "IsDefault": false,
  "RecipientLimitExternalPerHour": 0,
  "RecipientLimitInternalPerHour": 0,
  "RecipientLimitPerDay": 0,
  "ActionWhenThresholdReached": "BlockUserForToday",
  "AutoForwardingMode": false,
  "NotifyOutboundSpamRecipients": [],
  "NotifyOutboundSpam": false,
  "WhenCreated": "2026-05-29T18:44:55+03:00",
  "WhenChanged": "2026-05-29T18:44:55+03:00",
  "BccSuspiciousOutboundAdditionalRecipients": [],
  "BccSuspiciousOutboundMail": false,
  "ConfigurationType": "HostedOutboundSpamFilterPolicy",
  "DistinguishedName": "CN=exonaut-audit-hosf,CN=Outbound Spam Filter,CN=Transport Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
  "Enabled": false,
  "ExchangeObjectId": "0f044e81-d7f8-46d9-8489-e3a7e9fdaa57",
  "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:55Z",
  "WhenCreatedUTC": "2026-05-29T15:44:55Z"
}

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

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

Get a single hostedOutboundSpamFilterPolicies entry by Identity.

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

Get a single hostedOutboundSpamFilterPolicies entry

Returns one outbound spam filter policy by identity. Backed by Get-HostedOutboundSpamFilterPolicy with -Identity {key}; returns a 404 when the identity doesn’t resolve.

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#hostedOutboundSpamFilterPolicies/$entity",
  "Id": "Default",
  "Name": "Default",
  "Identity": "Default",
  "AdminDisplayName": "",
  "Guid": "8da3edf2-39f0-490c-a5b4-ffe67c7a38a1",
  "IsDefault": true,
  "RecipientLimitExternalPerHour": 200,
  "RecipientLimitInternalPerHour": 200,
  "RecipientLimitPerDay": 1000,
  "ActionWhenThresholdReached": "BlockUser",
  "AutoForwardingMode": false,
  "NotifyOutboundSpamRecipients": [
    "[email protected]"
  ],
  "NotifyOutboundSpam": true,
  "WhenCreated": "2026-03-30T17:42:00+03:00",
  "WhenChanged": "2026-03-30T17:42:08+03:00",
  "BccSuspiciousOutboundAdditionalRecipients": [
    "[email protected]"
  ],
  "BccSuspiciousOutboundMail": true,
  "ConfigurationType": "HostedOutboundSpamFilterPolicy",
  "DistinguishedName": "CN=Default,CN=Outbound Spam Filter,CN=Transport Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
  "Enabled": false,
  "ExchangeObjectId": "bc3ac7f5-3306-4094-b9c6-9b2e079e3e6a",
  "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:00Z"
}

Notes: The {key} accepts the policy Name/Identity (e.g. ‘Default’) or its Guid.

Related: GET /exchange/v1.0/hostedOutboundSpamFilterPolicies

Get a single hostedOutboundSpamFilterPolicies entry - not found

Returns a 404 with the canonical error envelope when the supplied identity does not resolve to any outbound spam filter policy. Backed by Get-HostedOutboundSpamFilterPolicy.

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

Notes: The {key} is echoed in the error message; correlationId aids tracing in logs.

Related: GET /exchange/v1.0/hostedOutboundSpamFilterPolicies

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

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

Parameter	In	Type	Required	Description
actionWhenThresholdReached	body
adminDisplayName	body
autoForwardingMode	body
bccSuspiciousOutboundAdditionalRecipients	body
bccSuspiciousOutboundMail	body
notifyOutboundSpam	body
notifyOutboundSpamRecipients	body
recipientLimitExternalPerHour	body
recipientLimitInternalPerHour	body
recipientLimitPerDay	body
dryRun	query	bool (switch)

Update an outbound spam filter policy

Partially updates a hosted outbound spam filter policy via Set-HostedOutboundSpamFilterPolicy. Only the body fields present are passed to the cmdlet; returns 200 with the post-Set entity.

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

{
  "actionWhenThresholdReached": "BlockUserForToday",
  "recipientLimitExternalPerHour": 400,
  "notifyOutboundSpam": true,
  "notifyOutboundSpamRecipients": [
    "[email protected]"
  ]
}

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

{
  "Identity": "exonaut-sample-hostedOutboundSpamFilterPolicies",
  "Name": "exonaut-sample-hostedOutboundSpamFilterPolicies",
  "ActionWhenThresholdReached": "BlockUserForToday",
  "RecipientLimitExternalPerHour": 400,
  "NotifyOutboundSpam": true,
  "NotifyOutboundSpamRecipients": [
    "[email protected]"
  ]
}

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

Related: GET /exchange/v1.0/hostedOutboundSpamFilterPolicies

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

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

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

Parameter	In	Type	Required	Description
dryRun	query	bool (switch)

Delete a outbound spam filter policy

Removes the outbound spam filter policy by Identity. Returns 204. Backed by Remove-HostedOutboundSpamFilterPolicy.

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

HTTP/1.1 204 No Content

Related: POST /exchange/v1.0/hostedOutboundSpamFilterPolicies

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