mailboxSearches

In-Place Mailbox Searches. Legacy in-place searches that find and hold mailbox content for discovery. The mailboxSearches entity set lives under /exchange/v1.0/mailboxSearches in the eDiscovery & audit category.

Fact	Value
Path	/exchange/v1.0/mailboxSearches
Category	eDiscovery & audit
Tier	Tier 9, Hybrid and organization
Read role	Compliance.Read.All (Community)
Write role	Compliance.ReadWrite.All (Enterprise)
Backing cmdlets	Get-MailboxSearch, Set-MailboxSearch, New-MailboxSearch, Remove-MailboxSearch, Start-MailboxSearch, Stop-MailboxSearch

Routes

Method	Path	Synopsis	Role	Plan
GET	/exchange/v1.0/mailboxSearches	List mailboxSearches entries.	Compliance.Read	Community
POST	/exchange/v1.0/mailboxSearches	Create a new mailboxSearches 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.	Compliance.ReadWrite	Enterprise
GET	/exchange/v1.0/mailboxSearches/{key}	Get a single mailboxSearches entry by Identity.	Compliance.Read	Community
PATCH	/exchange/v1.0/mailboxSearches/{key}	Partial update of the mailboxSearches at /mailboxSearches/{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).	Compliance.ReadWrite	Enterprise
DELETE	/exchange/v1.0/mailboxSearches/{key}	DELETE /mailboxSearches/{key} - Remove-MailboxSearch only accepts -Identity + universal switches (no -Force).	Compliance.ReadWrite	Enterprise
POST	/exchange/v1.0/mailboxSearches/{key}/start	POST /mailboxSearches/{key}/start - bound action via Start-MailboxSearch. Use ?resume=true to resume a paused search; ?statisticsStartIndex=N for partial-result paging.	Compliance.ReadWrite	Enterprise
POST	/exchange/v1.0/mailboxSearches/{key}/stop	POST /mailboxSearches/{key}/stop - bound action via Stop-MailboxSearch.	Compliance.ReadWrite	Enterprise

GET /exchange/v1.0/mailboxSearches

List mailboxSearches entries.

Backing cmdlet: Get-MailboxSearch. Role: Compliance.Read (Community).

Parameter	In	Type	Required	Description
inPlaceHoldIdentity	query	string		Find the mailbox search/hold by the GUID of an In-Place Hold a user is placed on (Get-MailboxSearch -InPlaceHoldIdentity). The GUIDs come from a mailbox’s InPlaceHolds property. Optional; primary discovery path for ‘which search holds this user’.
all	query	bool (switch)		Return all results instead of the EXO default of 1000. Maps -ResultSize Unlimited on Get-MailboxSearch; prevents silent truncation in large tenants.

List mailboxSearches

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

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

HTTP/1.1 200 OK

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

POST /exchange/v1.0/mailboxSearches

Create a new mailboxSearches 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-MailboxSearch. Role: Compliance.ReadWrite (Enterprise).

Parameter	In	Type	Required	Description
name	body		yes
allPublicFolderSources	body
allSourceMailboxes	body
description	body
endDate	body
estimateOnly	body	boolean (switch)
excludeDuplicateMessages	body
includeKeywordStatistics	body	boolean (switch)
includeUnsearchableItems	body	boolean (switch)
inPlaceHoldEnabled	body
inPlaceHoldIdentity	body
itemHoldPeriod	body
language	body
logLevel	body
messageTypes	body
recipients	body
searchQuery	body
senders	body
sourceMailboxes	body
startDate	body
statusMailRecipients	body
targetMailbox	body
dryRun	query	bool (switch)

Create rejected - missing required name

New-MailboxSearch requires Name. Omitting it returns a 400 canonical error envelope before the cmdlet is invoked.

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

{
  "description": "EXONAUT sample search missing its name",
  "sourceMailboxes": [
    "legal@contoso.com"
  ]
}

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

{
  "error": {
    "code": "BadRequest",
    "message": "The 'name' field is required for New-MailboxSearch.",
    "target": "name"
  },
  "correlationId": "0HN7K2A9QF1XC"
}

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

Related: GET /exchange/v1.0/mailboxSearches

Create a mailbox search

Creates an in-place eDiscovery mailbox search via New-MailboxSearch. Body keys map 1:1 to the cmdlet parameters (camelCased); only Name is required.

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

{
  "name": "exonaut-sample-mailboxSearches",
  "description": "EXONAUT sample legal-hold discovery search",
  "sourceMailboxes": [
    "legal@contoso.com",
    "compliance@contoso.com"
  ],
  "searchQuery": "subject:\"Project Apollo\" AND received>=01/01/2026",
  "startDate": "2026-01-01T00:00:00Z",
  "endDate": "2026-05-29T00:00:00Z",
  "excludeDuplicateMessages": true,
  "logLevel": "Full",
  "statusMailRecipients": [
    "ediscovery-admin@contoso.com"
  ]
}

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

{
  "Identity": "exonaut-sample-mailboxSearches",
  "Id": "exonaut-sample-mailboxSearches",
  "Name": "exonaut-sample-mailboxSearches",
  "Description": "EXONAUT sample legal-hold discovery search",
  "SourceMailboxes": [
    "legal@contoso.com",
    "compliance@contoso.com"
  ],
  "SearchQuery": "subject:\"Project Apollo\" AND received>=01/01/2026",
  "StartDate": "2026-01-01T00:00:00Z",
  "EndDate": "2026-05-29T00:00:00Z",
  "ExcludeDuplicateMessages": true,
  "LogLevel": "Full",
  "Status": "NotStarted"
}

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

Related: GET /exchange/v1.0/mailboxSearches

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

Get a single mailboxSearches entry by Identity.

Backing cmdlet: Get-MailboxSearch. Role: Compliance.Read (Community).

Get a single mailboxSearches entry

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

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

HTTP/1.1 200 OK

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

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

Partial update of the mailboxSearches at /mailboxSearches/{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-MailboxSearch. Role: Compliance.ReadWrite (Enterprise).

Parameter	In	Type	Required	Description
allPublicFolderSources	body
allSourceMailboxes	body
description	body
endDate	body
excludeDuplicateMessages	body
includeUnsearchableItems	body
inPlaceHoldEnabled	body
itemHoldPeriod	body
language	body
logLevel	body
messageTypes	body
name	body
recipients	body
searchQuery	body
senders	body
sourceMailboxes	body
startDate	body
statisticsStartIndex	body
statusMailRecipients	body
targetMailbox	body
dryRun	query	bool (switch)

Update a mailbox search

Partial update of an existing mailbox search via Set-MailboxSearch. Only the body fields supplied are passed to the cmdlet; returns 200 with the post-Set entity.

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

{
  "description": "EXONAUT sample search - widened date range",
  "endDate": "2026-06-30T00:00:00Z",
  "logLevel": "Basic"
}

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

{
  "Identity": "exonaut-sample-mailboxSearches",
  "Id": "exonaut-sample-mailboxSearches",
  "Name": "exonaut-sample-mailboxSearches",
  "Description": "EXONAUT sample search - widened date range",
  "EndDate": "2026-06-30T00:00:00Z",
  "LogLevel": "Basic",
  "Status": "NotStarted"
}

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

Related: GET /exchange/v1.0/mailboxSearches

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

DELETE /mailboxSearches/{key} - Remove-MailboxSearch only accepts -Identity + universal switches (no -Force).

Backing cmdlet: Remove-MailboxSearch. Role: Compliance.ReadWrite (Enterprise).

Parameter	In	Type	Required	Description
dryRun	query	bool (switch)

Delete a mailbox search

Removes a mailbox search via Remove-MailboxSearch (accepts only -Identity plus universal switches). Returns 204 No Content on success.

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

POST /exchange/v1.0/mailboxSearches/{key}/start

POST /mailboxSearches/{key}/start - bound action via Start-MailboxSearch. Use ?resume=true to resume a paused search; ?statisticsStartIndex=N for partial-result paging.

Backing cmdlet: Start-MailboxSearch. Role: Compliance.ReadWrite (Enterprise).

Parameter	In	Type	Required	Description
resume	query	bool (switch)
statisticsStartIndex	query	int
force	query	bool (switch)
dryRun	query	bool (switch)

Start a mailbox search

Sub-resource action of the mailbox search at GET /mailboxSearches/{key} - runs the search via Start-MailboxSearch. Use ?resume=true to resume a paused search and ?statisticsStartIndex=N for partial-result paging. Returns 204 No Content.

POST /exchange/v1.0/mailboxSearches/{key}/start 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/mailboxSearches

POST /exchange/v1.0/mailboxSearches/{key}/stop

POST /mailboxSearches/{key}/stop - bound action via Stop-MailboxSearch.

Backing cmdlet: Stop-MailboxSearch. Role: Compliance.ReadWrite (Enterprise).

Parameter	In	Type	Required	Description
dryRun	query	bool (switch)

Stop a mailbox search

Sub-resource action of the mailbox search at GET /mailboxSearches/{key} - halts an in-progress search via Stop-MailboxSearch. Returns 204 No Content.

POST /exchange/v1.0/mailboxSearches/{key}/stop 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/mailboxSearches

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