emailAddressPolicies

Email Address Policies. Rules that automatically stamp recipient email addresses by format. The emailAddressPolicies entity set lives under /exchange/v1.0/emailAddressPolicies in the Mail flow category.

Fact	Value
Path	`/exchange/v1.0/emailAddressPolicies`
Category	Mail flow
Tier	Tier 9, Hybrid and organization
Read role	`OrganizationConfig.Read.All` (Community)
Write role	`MailFlow.ReadWrite.All` (Pro)
Backing cmdlets	Get-EmailAddressPolicy, Set-EmailAddressPolicy, New-EmailAddressPolicy, Remove-EmailAddressPolicy, Update-EmailAddressPolicy

Routes

Method	Path	Synopsis	Role	Plan
GET	`/exchange/v1.0/emailAddressPolicies`	List emailAddressPolicies entries.	`OrganizationConfig.Read`	Community
POST	`/exchange/v1.0/emailAddressPolicies`	Create a new emailAddressPolicies entry. Body keys map 1:1 to New-EmailAddressPolicy parameter names (camelCased). Required: name. Provide ONE of (enabledEmailAddressTemplates \| enabledPrimarySMTPAddressTemplate). For M365-group scoping, set includeUnifiedGroupRecipients:true + managedByFilter. Returns 201 + Location + the freshly-fetched policy.	`MailFlow.ReadWrite`	Pro
GET	`/exchange/v1.0/emailAddressPolicies/{key}`	Get a single emailAddressPolicies entry by Identity.	`OrganizationConfig.Read`	Community
PATCH	`/exchange/v1.0/emailAddressPolicies/{key}`	Partial update of the emailAddressPolicies at /emailAddressPolicies/{key}. Body keys map 1:1 to Set-EmailAddressPolicy parameters. Use `name` to rename. Returns 200 + the post-Set policy.	`MailFlow.ReadWrite`	Pro
DELETE	`/exchange/v1.0/emailAddressPolicies/{key}`	Remove the emailAddressPolicies at /emailAddressPolicies/{key}. Returns 204 with no body. NOTE: the built-in “Default Policy” is protected and cannot be removed.	`MailFlow.ReadWrite`	Pro

GET /exchange/v1.0/emailAddressPolicies

List emailAddressPolicies entries.

Backing cmdlet: Get-EmailAddressPolicy. Role: OrganizationConfig.Read (Community).

List all email address policies

List the tenant’s email address policies. Each policy is a (filter, templates) pair that controls how proxy SMTP addresses get auto-assigned to matching recipients. The built-in ‘Default Policy’ is the catch-all; custom policies have higher priority (lower Priority number = higher precedence).

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

HTTP/1.1 200 OK

{
  "@odata.context": "https://api.contoso.com/exchange/v1.0/$metadata#emailAddressPolicies",
  "value": [
    {
      "Id": "default-policy",
      "Name": "Default Policy",
      "Identity": "default-policy",
      "Priority": "Lowest",
      "EnabledEmailAddressTemplates": [
        "SMTP:%m@contoso.com"
      ],
      "IncludedRecipients": "AllRecipients",
      "WhenCreated": "2024-01-01T00:00:00Z"
    },
    {
      "Id": "finance-policy",
      "Name": "Finance Department Policy",
      "Identity": "finance-policy",
      "Priority": 1,
      "EnabledEmailAddressTemplates": [
        "SMTP:%g.%s@finance.contoso.com",
        "smtp:%g.%s@contoso.com"
      ],
      "IncludedRecipients": "MailboxUsers",
      "ConditionalDepartment": [
        "Finance"
      ],
      "WhenCreated": "2025-03-15T10:00:00Z"
    }
  ]
}

POST /exchange/v1.0/emailAddressPolicies

Create a new emailAddressPolicies entry. Body keys map 1:1 to New-EmailAddressPolicy parameter names (camelCased). Required: name. Provide ONE of (enabledEmailAddressTemplates | enabledPrimarySMTPAddressTemplate). For M365-group scoping, set includeUnifiedGroupRecipients:true + managedByFilter. Returns 201 + Location + the freshly-fetched policy.

Email address policies control how proxy SMTP addresses get auto-assigned to recipients. Each policy pairs a filter with a set of templates (e.g. “SMTP:%g.%s@contoso.com”). Cloud-EXO limitation (load-bearing for slice 21): the Wiki documents the on-prem superset of params including includedRecipients, conditional* attribute filters, and custom recipientFilter OPATH. Cloud EXO ships a SLIMMED-DOWN cmdlet that REJECTS those at runtime with “A parameter cannot be found that matches parameter name ‘X’”. Cloud tenants can scope policies only by: The system’s default filter (all recipients) - implicit when no filter param is sentM365 group membership via includeUnifiedGroupRecipients + managedByFilter For more granular targeting, manage proxy addresses directly on recipients via PATCH /mailboxes/{key} (or sibling recipient types).Pass ?dryRun=true for a -WhatIf preview before the policy actually gets distributed.

Backing cmdlet: New-EmailAddressPolicy. Role: MailFlow.ReadWrite (Pro).

Parameter	In	Type	Required
`name`	body		yes
`enabledEmailAddressTemplates`	body
`enabledPrimarySMTPAddressTemplate`	body
`includeUnifiedGroupRecipients`	body	boolean (switch)
`managedByFilter`	body
`priority`	body
`dryRun`	query	bool (switch)

Create an M365-group-scoped email address policy

Create a new email address policy via New-EmailAddressPolicy. Required: name + ONE of (enabledEmailAddressTemplates | enabledPrimarySMTPAddressTemplate). This example uses the M365-group (Unified Group) scoping mode: includeUnifiedGroupRecipients:true + managedByFilter selects which M365 groups the policy targets, and the SMTP template stamps proxy addresses on group memberships. Cloud EXO does NOT accept the on-prem precanned-filter params (includedRecipients, conditional*, recipientFilter) - for granular per-recipient targeting, manage proxy addresses directly via PATCH /mailboxes/{key}.

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

{
  "name": "M365 Groups - Marketing Domain Policy",
  "priority": 1,
  "enabledPrimarySMTPAddressTemplate": "%g@marketing.contoso.com",
  "includeUnifiedGroupRecipients": true,
  "managedByFilter": "Department -eq 'Marketing'"
}

HTTP/1.1 201 Created
Location: /exchange/v1.0/emailAddressPolicies/M365%20Groups%20-%20Marketing%20Domain%20Policy

{
  "@odata.context": "https://api.contoso.com/exchange/v1.0/$metadata#emailAddressPolicies/$entity",
  "Id": "marketing-m365-policy",
  "Name": "M365 Groups - Marketing Domain Policy",
  "Identity": "marketing-m365-policy",
  "Priority": 1,
  "EnabledPrimarySMTPAddressTemplate": "%g@marketing.contoso.com",
  "EnabledEmailAddressTemplates": [
    "SMTP:%g@marketing.contoso.com"
  ],
  "RecipientFilter": "((RecipientType -eq 'GroupMailbox') -and (Department -eq 'Marketing'))",
  "IncludedRecipients": "None",
  "WhenCreated": "2026-05-25T10:00:00Z"
}

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

Get a single emailAddressPolicies entry by Identity.

Backing cmdlet: Get-EmailAddressPolicy. Role: OrganizationConfig.Read (Community).

Get an email address policy by Identity

Get a single email address policy by Identity (Name or GUID). Returned object includes the policy’s templates, filter (precanned conditional* attributes OR custom recipientFilter), and priority.

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

HTTP/1.1 200 OK

{
  "@odata.context": "https://api.contoso.com/exchange/v1.0/$metadata#emailAddressPolicies/$entity",
  "Id": "finance-policy",
  "Name": "Finance Department Policy",
  "Identity": "finance-policy",
  "Priority": 1,
  "EnabledEmailAddressTemplates": [
    "SMTP:%g.%s@finance.contoso.com",
    "smtp:%g.%s@contoso.com"
  ],
  "DisabledEmailAddressTemplates": [],
  "IncludedRecipients": "MailboxUsers",
  "ConditionalDepartment": [
    "Finance"
  ],
  "ConditionalCompany": [],
  "ConditionalStateOrProvince": [],
  "RecipientFilter": null,
  "RecipientContainer": null,
  "WhenCreated": "2025-03-15T10:00:00Z",
  "WhenChanged": "2025-04-02T14:22:11Z"
}

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

Partial update of the emailAddressPolicies at /emailAddressPolicies/{key}. Body keys map 1:1 to Set-EmailAddressPolicy parameters. Use name to rename. Returns 200 + the post-Set policy.

Set-EmailAddressPolicy has a single parameter set, so any combination of writable fields is accepted. The forceUpgrade switch promotes a pre-Exchange-2007 policy schema in place - usually unnecessary on cloud tenants but exposed for parity. After PATCH, run POST /recipients/{key}/update on each in-scope recipient to apply the policy’s template changes (the policy itself doesn’t push addresses; Update-Recipient does).

Backing cmdlet: Set-EmailAddressPolicy. Role: MailFlow.ReadWrite (Pro).

Parameter	In	Type
`enabledEmailAddressTemplates`	body
`enabledPrimarySMTPAddressTemplate`	body
`name`	body
`priority`	body
`dryRun`	query	bool (switch)

Update an email address policy

Partially updates the email address policy identified by {key}, invoking Set-EmailAddressPolicy. Body keys map 1:1 to Set-EmailAddressPolicy parameters (camelCased); use name to rename.

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

{
  "enabledPrimarySMTPAddressTemplate": "SMTP:%g.%s@contoso.com",
  "priority": 2
}

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

{
  "Id": "exonaut-sample-emailAddressPolicies",
  "Identity": "exonaut-sample-emailAddressPolicies",
  "Name": "exonaut-sample-emailAddressPolicies",
  "EnabledPrimarySMTPAddressTemplate": "SMTP:%g.%s@contoso.com",
  "EnabledEmailAddressTemplates": [
    "SMTP:%g.%s@contoso.com"
  ],
  "Priority": 2,
  "Enabled": true
}

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

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

Remove the emailAddressPolicies at /emailAddressPolicies/{key}. Returns 204 with no body. NOTE: the built-in “Default Policy” is protected and cannot be removed.

Removing a policy does NOT strip the proxy addresses it already stamped onto recipients - those persist on the recipient’s emailAddresses collection until manually removed via PATCH /mailboxes/{key} (etc.) with the appropriate emailAddresses mutation. The cmdlet will reject removal of the system “Default Policy” - surfaces as a canonical 500 from the cmdlet (no special guard on our side).

Backing cmdlet: Remove-EmailAddressPolicy. Role: MailFlow.ReadWrite (Pro).

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

Delete an email address policy

Removes the email address policy identified by {key}, invoking Remove-EmailAddressPolicy. Returns 204 with no body. The built-in “Default Policy” is protected and cannot be removed.

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

HTTP/1.1 204 No Content

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.