globalAddressLists

Global Address List. Define the tenant Global Address List shown in Outlook. The globalAddressLists entity set lives under /exchange/v1.0/globalAddressLists in the Address book category.

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

Routes

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

GET /exchange/v1.0/globalAddressLists

List globalAddressLists entries.

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

Parameter	In	Type	Required	Description
defaultOnly	query	bool (switch)		Filter the results so only the default GAL is returned. Maps -DefaultOnly on Get-GlobalAddressList.

List globalAddressLists

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

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#globalAddressLists",
  "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/globalAddressLists/{key}

POST /exchange/v1.0/globalAddressLists

Create a new globalAddressLists 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-GlobalAddressList. 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
includedRecipients	body
recipientFilter	body
dryRun	query	bool (switch)

Create a global address list - missing required name (400)

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

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

{
  "includedRecipients": "MailboxUsers"
}

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

{
  "error": {
    "code": "BadRequest",
    "message": "The required field 'name' is missing from the request body.",
    "target": "name"
  },
  "correlationId": "0HN7K2A9QH3PV:00000003"
}

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

Related: GET /exchange/v1.0/globalAddressLists

Create a global address list

Creates a new global address list (GAL) definition backed by New-GlobalAddressList. A GAL aggregates recipients matching its precanned IncludedRecipients filter or a custom RecipientFilter OPATH expression.

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

{
  "name": "exonaut-sample-globalAddressLists",
  "includedRecipients": "MailboxUsers",
  "conditionalCompany": "Contoso",
  "conditionalDepartment": "Engineering"
}

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

{
  "Id": "exonaut-sample-globalAddressLists",
  "Identity": "exonaut-sample-globalAddressLists",
  "name": "exonaut-sample-globalAddressLists",
  "includedRecipients": "MailboxUsers",
  "conditionalCompany": "Contoso",
  "conditionalDepartment": "Engineering"
}

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

Related: GET /exchange/v1.0/globalAddressLists

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

Get a single globalAddressLists entry by Identity.

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

Get a single globalAddressLists entry

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

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#globalAddressLists/$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/globalAddressLists

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

Partial update of the globalAddressLists at /globalAddressLists/{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-GlobalAddressList. 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
includedRecipients	body
name	body
recipientFilter	body
dryRun	query	bool (switch)

Update a global address list

Partial update of a global address list backed by Set-GlobalAddressList. Only the body fields present are passed to the cmdlet; returns 200 with the post-Set entity.

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

{
  "conditionalDepartment": "Research",
  "conditionalStateOrProvince": "WA"
}

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

{
  "Id": "exonaut-sample-globalAddressLists",
  "Identity": "exonaut-sample-globalAddressLists",
  "name": "exonaut-sample-globalAddressLists",
  "conditionalDepartment": "Research",
  "conditionalStateOrProvince": "WA"
}

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

Related: GET /exchange/v1.0/globalAddressLists

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

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

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

Parameter	In	Type	Required	Description
dryRun	query	bool (switch)

Delete a global address list

Removes a global address list definition backed by Remove-GlobalAddressList. Returns 204 with no body.

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

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