addressLists

Address Lists. Filtered recipient lists shown in Outlook’s address book. The addressLists entity set lives under /exchange/v1.0/addressLists in the Address book category.

Fact	Value
Path	/exchange/v1.0/addressLists
Category	Address book
Tier	Tier 3, Mail flow
Read role	MailFlow.Read.All (Community)
Write role	MailFlow.ReadWrite.All (Pro)
Backing cmdlets	Get-AddressList, Set-AddressList, New-AddressList, Remove-AddressList

Routes

Method	Path	Synopsis	Role	Plan
GET	/exchange/v1.0/addressLists	List addressLists entries.	MailFlow.Read	Community
POST	/exchange/v1.0/addressLists	Create a new addressLists 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.	MailFlow.ReadWrite	Pro
GET	/exchange/v1.0/addressLists/{key}	Get a single addressLists entry by Identity.	MailFlow.Read	Community
PATCH	/exchange/v1.0/addressLists/{key}	Partial update of the addressLists at /addressLists/{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).	MailFlow.ReadWrite	Pro
DELETE	/exchange/v1.0/addressLists/{key}	DELETE /addressLists/{key}. Use ?recursive=true to also remove any nested address lists (Remove-AddressList -Recursive).	MailFlow.ReadWrite	Pro

GET /exchange/v1.0/addressLists

List addressLists entries.

Backing cmdlet: Get-AddressList. Role: MailFlow.Read (Community).

Parameter	In	Type	Required	Description
searchText	query	string		Optional: server-side filter (Get-AddressList -SearchText). Returns only address lists whose name or display name contains this text.
container	query	string		Optional: filter by container path. Maps -Container on Get-AddressList; returns only address lists under the specified path (e.g. “" for All Address Lists, or “\All Users”). Cannot be combined with searchText.

List addressLists

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

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

HTTP/1.1 200 OK

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

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

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

POST /exchange/v1.0/addressLists

Create a new addressLists 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-AddressList. Role: MailFlow.ReadWrite (Pro).

Parameter	In	Type	Required	Description
name	body		yes
conditionalCompany	body
conditionalCustomAttribute1	body
conditionalCustomAttribute10	body
conditionalCustomAttribute11	body
conditionalCustomAttribute12	body
conditionalCustomAttribute13	body
conditionalCustomAttribute14	body
conditionalCustomAttribute15	body
conditionalCustomAttribute2	body
conditionalCustomAttribute3	body
conditionalCustomAttribute4	body
conditionalCustomAttribute5	body
conditionalCustomAttribute6	body
conditionalCustomAttribute7	body
conditionalCustomAttribute8	body
conditionalCustomAttribute9	body
conditionalDepartment	body
conditionalStateOrProvince	body
container	body
displayName	body
includedRecipients	body
recipientFilter	body
dryRun	query	bool (switch)

Create an address list - missing required name (400)

New-AddressList requires the name field. Omitting it fails body validation before the cmdlet is invoked and returns the canonical 400 envelope.

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

{
  "displayName": "Exonaut Sample Address List"
}

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

{
  "error": {
    "code": "BadRequest",
    "message": "The 'name' field is required.",
    "target": "name"
  },
  "correlationId": "0HN7EXONAUT0SAMPLE0ADDRESSLISTS01"
}

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

Related: GET /exchange/v1.0/addressLists

Create an address list

Creates a new address list (a named subset of the GAL) via the New-AddressList cmdlet. Body fields map 1:1 to the cmdlet’s parameters, camelCased. Returns 201 with a Location header and the freshly-fetched entity.

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

{
  "name": "exonaut-sample-addressLists",
  "displayName": "Exonaut Sample Address List",
  "includedRecipients": "MailboxUsers",
  "conditionalCompany": "Contoso"
}

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

{
  "Id": "exonaut-sample-addressLists",
  "Identity": "exonaut-sample-addressLists",
  "Name": "exonaut-sample-addressLists",
  "DisplayName": "Exonaut Sample Address List",
  "IncludedRecipients": "MailboxUsers",
  "ConditionalCompany": [
    "Contoso"
  ]
}

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

Related: GET /exchange/v1.0/addressLists

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

Get a single addressLists entry by Identity.

Backing cmdlet: Get-AddressList. Role: MailFlow.Read (Community).

Get a single addressLists entry

Stub auto-generated example for GET /addressLists/{key}. Backing cmdlet: Get-AddressList with -Identity {key}. Returns the full entity body; 404 if the identity doesn’t resolve.

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#addressLists/$entity"
}

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

Related: GET /exchange/v1.0/addressLists

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

Partial update of the addressLists at /addressLists/{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-AddressList. Role: MailFlow.ReadWrite (Pro).

Parameter	In	Type	Required	Description
conditionalCompany	body
conditionalCustomAttribute1	body
conditionalCustomAttribute10	body
conditionalCustomAttribute11	body
conditionalCustomAttribute12	body
conditionalCustomAttribute13	body
conditionalCustomAttribute14	body
conditionalCustomAttribute15	body
conditionalCustomAttribute2	body
conditionalCustomAttribute3	body
conditionalCustomAttribute4	body
conditionalCustomAttribute5	body
conditionalCustomAttribute6	body
conditionalCustomAttribute7	body
conditionalCustomAttribute8	body
conditionalCustomAttribute9	body
conditionalDepartment	body
conditionalStateOrProvince	body
displayName	body
includedRecipients	body
name	body
recipientFilter	body
dryRun	query	bool (switch)

Update an address list

Partial update of the address list at /addressLists/{key} via the Set-AddressList cmdlet. Only the body fields present are passed to the cmdlet. Returns 200 with the post-Set entity (rename-aware re-fetch when name is in the body).

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

{
  "displayName": "Exonaut Sample Address List (updated)",
  "includedRecipients": "AllRecipients"
}

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

{
  "Id": "exonaut-sample-addressLists",
  "Identity": "exonaut-sample-addressLists",
  "Name": "exonaut-sample-addressLists",
  "DisplayName": "Exonaut Sample Address List (updated)",
  "IncludedRecipients": "AllRecipients"
}

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

Related: GET /exchange/v1.0/addressLists

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

DELETE /addressLists/{key}. Use ?recursive=true to also remove any nested address lists (Remove-AddressList -Recursive).

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

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

Delete an address list

Removes the address list at /addressLists/{key} via the Remove-AddressList cmdlet. Use ?recursive=true to also remove any nested address lists. Returns 204 No Content on success.

DELETE /exchange/v1.0/addressLists/{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.

Related: GET /exchange/v1.0/addressLists

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