Search Emails
search-emailsFind Outlook emails by sender, recipient, subject, date, folder, or query; list results, group conversations, sync changes, and search shared mailboxes read-only.
Instructions
Search, list, delta-sync or thread-group emails (read-only); parameters set the mode. No params: recent emails in folder (default inbox). query/from/to/subject/date filters: search, combined as an OData filter. searchExpression (deprecated alias kqlQuery): a raw Graph $search expression. deltaMode: true: current state plus a deltaToken to pass back next time for changes only. groupByConversation: true: conversation threads. conversationId: every message in one thread. internetMessageId: the message with that RFC Message-ID. sharedMailbox (alias email) searches a shared/delegated mailbox, custom folders and nested paths included. Graph $search takes no other filter: a query that needs one is answered by OData filters or local matching, and a searchExpression reports the filters it could not apply. _meta.searchMetadata names the strategy that answered. Returns up to count messages (id/subject/from/receivedDateTime/preview); outputVerbosity expands them.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "search-emails"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Filter by recipient email/name. Personal Outlook.com accounts reject the server-side recipient filter, in which case this is matched locally over the 500 most recent messages only (raise with `OUTLOOK_SEARCH_SCAN_LIMIT`). On a large archive, pair `to` with `receivedAfter`/`receivedBefore` to reach older mail; the response says so when the scan was truncated. | |
| from | No | Filter by sender email/name | |
| count | No | Number of results (list default: 25, search default: 10, max: 50). There is no page cursor: when the result says more emails are available, raise `count` or narrow `receivedAfter`/`receivedBefore`. | |
| No | Alias for `sharedMailbox`. | ||
| query | No | Free-text search. Omit for list mode. Alone or with only date and boolean filters, it is sent to Graph `$search`, which matches subject, body and sender. `$search` takes no other filters, so those are applied to its results, newest first, reading at most 250. With `from`, `to` or `subject`, those go to Graph as a filter and `query` is matched against each result's subject, preview and sender. If nothing passes, this falls back to a subject substring match (all words must appear in the subject) with the filters applied server-side. The response names the strategy used and says when coverage was partial. | |
| folder | No | Email folder (default: 'inbox'). Accepts a well-known name, a custom/localized display name, or a nested path like `Inbox/Subfolder`. | |
| subject | No | Filter by subject | |
| kqlQuery | No | DEPRECATED alias for `searchExpression` (this was never full KQL — it is a Graph `$search` expression). | |
| deltaMode | No | Enable delta sync mode. Returns only changes since last sync. Use deltaToken for subsequent calls; an initial sync larger than `maxResults` arrives over several pages, each returning a continuation token to pass back until a delta token is returned. Honors `sharedMailbox`/`email` (and custom `folder` paths) to sync within a shared/delegated mailbox. | |
| deltaToken | No | Token from previous delta call for incremental sync (deltaMode only). The token is authoritative — it encodes its own mailbox and folder, so `folder`/`sharedMailbox` are ignored and a token from a different mailbox is rejected. | |
| maxResults | No | Delta sync page size (deltaMode only): 1-200, default 100, sent to Graph as the `Prefer: odata.maxpagesize` header. It sizes each page, not the whole sync: while a page returns a continuation token, keep calling with that token until a delta token is returned, and pass the same `maxResults` on every page (an omitted value means 100). | |
| unreadOnly | No | Filter to unread emails only | |
| receivedAfter | No | Filter emails received after date (ISO 8601) | |
| sharedMailbox | No | Email address of a shared/delegated mailbox to search (default: the signed-in account). Combine with `folder` (incl. custom subfolders/paths) or `searchAllFolders`. Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance). | |
| conversationId | No | Get the messages in a conversation thread by conversationId, oldest first (up to 100; a longer thread is marked truncated — use `export target=conversation` for up to 1000). Honors `sharedMailbox`/`email` to thread within a shared/delegated mailbox. | |
| hasAttachments | No | Filter to emails with attachments | |
| includeHeaders | No | Include email headers for each message (conversationId only) | |
| receivedBefore | No | Filter emails received before date (ISO 8601) | |
| outputVerbosity | No | Output detail level (default: standard) | |
| searchAllFolders | No | Search across all mail folders | |
| searchExpression | No | Raw Microsoft Graph `$search` expression (KQL), e.g. `subject:"quarterly report" AND received>=2026-01-01`, `invoice OR receipt`. It takes the place of the other search params. It is sent to Graph as one double-quoted string, the form Graph reads as KQL (as written when it already is one, otherwise wrapped with its `"` and `\` escaped); `receivedAfter`/`receivedBefore`/`hasAttachments`/`unreadOnly` are then not applied (they come back in `droppedFilters`), so dates go in the expression. Operators are upper-case (`AND`, `OR`, `NOT`). Terms match whole words or their beginnings; results are newest first; with `searchAllFolders: true` Graph leaves out Deleted Items and Junk Email. Exception: an expression made only of `from:`/`to:`/`subject:` terms is sent as written, and when Graph rejects it (personal accounts do) or finds nothing it is run as OData filters: substring match, date and boolean params applied, strategy `raw-kql-translated`. Any other expression that finds nothing ends with no results. | |
| internetMessageId | No | Look up email by Message-ID header (e.g. <abc123@example.com>). For threading/deduplication. Honors `sharedMailbox`/`email` to look up within a shared/delegated mailbox. | |
| groupByConversation | No | List conversations (threads) grouped by conversationId, not individual emails. Honors `sharedMailbox`/`email` (and custom `folder` paths) to group within a shared/delegated mailbox. |