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": [
        "SecOps@contoso.com"
      ],
      "NotifyOutboundSpam": true,
      "WhenCreated": "2026-03-30T17:42:00+03:00",
      "WhenChanged": "2026-03-30T17:42:08+03:00",
      "BccSuspiciousOutboundAdditionalRecipients": [
        "SecOps@contoso.com"
      ],
      "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.

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
`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"
}

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": [
    "SecOps@contoso.com"
  ],
  "NotifyOutboundSpam": true,
  "WhenCreated": "2026-03-30T17:42:00+03:00",
  "WhenChanged": "2026-03-30T17:42:08+03:00",
  "BccSuspiciousOutboundAdditionalRecipients": [
    "SecOps@contoso.com"
  ],
  "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.

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.

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
`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": [
    "secops@contoso.com"
  ]
}

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

{
  "Identity": "exonaut-sample-hostedOutboundSpamFilterPolicies",
  "Name": "exonaut-sample-hostedOutboundSpamFilterPolicies",
  "ActionWhenThresholdReached": "BlockUserForToday",
  "RecipientLimitExternalPerHour": 400,
  "NotifyOutboundSpam": true,
  "NotifyOutboundSpamRecipients": [
    "secops@contoso.com"
  ]
}

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

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

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