search-emails
Search, list, delta-sync, or thread-group emails — six modes selected by parameters (read-only). With no params: lists recent emails in folder (default inbox).
Instructions
Search, list, delta-sync, or thread-group emails — six modes selected by parameters (read-only). With no params: lists recent emails in folder (default inbox). With query/from/to/subject/date filters: full search (combines via OData filter). With searchExpression (deprecated alias kqlQuery): a raw Microsoft Graph $search expression for advanced server-side search. With deltaMode: true: returns current state plus a deltaToken; pass the token back on the next call for incremental changes only — ideal for inbox monitoring. With groupByConversation: true: returns conversation threads. With conversationId: returns all messages in a single thread. With internetMessageId: looks up a message by its RFC Message-ID header. Personal Outlook.com accounts have limited $search support — this tool falls back through OData filters / boolean filters / recent listing automatically, but structured filters (from/subject/receivedAfter/hasAttachments/unreadOnly) return cleaner results. Returns paged messages with id/subject/from/receivedDateTime/preview by default; use outputVerbosity to expand.
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) | |
| query | No | Search query text. Omit for list mode. On personal Outlook.com accounts Graph `$search` is unavailable, so this falls back to a subject substring match (all words must appear in the subject) — precise, but it does NOT search message bodies. Use `searchExpression` when you need body content. | |
| folder | No | Email folder (default: 'inbox') | |
| subject | No | Filter by subject | |
| kqlQuery | No | DEPRECATED alias for `searchExpression` (this was never full KQL — it is a Graph `$search` expression). Prefer `searchExpression`. | |
| deltaMode | No | Enable delta sync mode. Returns only changes since last sync. Use deltaToken for subsequent calls. | |
| deltaToken | No | Token from previous delta call for incremental sync (deltaMode only) | |
| maxResults | No | Max results per page for delta sync (default: 100, max: 200) | |
| unreadOnly | No | Filter to unread emails only | |
| receivedAfter | No | Filter emails received after date (ISO 8601) | |
| conversationId | No | Get all messages in a conversation thread by conversationId. | |
| 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 for advanced server-side search, e.g. `subject:"invoice"`, `from:github.com`, or `foo OR bar`. Quote your own phrases; a single bare token is auto-quoted. Pair with `searchAllFolders: true` for cross-folder search. Bypasses other search params. NOTE: personal Outlook.com accounts reject field-scoped `$search` outright; since v3.10.0 recognised `from:`/`to:`/`subject:` expressions are translated into the closest equivalent OData filters and retried automatically (a `subject:` term becomes a substring match, so it is close but not identical) (reported as strategy `raw-kql-translated`). Expressions that cannot be translated exactly — free text, `AND`/`OR`, unknown prefixes — are not retried, so use `query` for those there. RELEVANCE, NOT RECENCY: an untranslated expression is answered by Graph `$search` over the whole message including the body, ranked by relevance and not sorted by date, so top hits can look unrelated to a caller expecting a subject match. `query` is the more predictable choice for a term you expect in a subject line; `searchExpression` is the one that reaches body text. | |
| internetMessageId | No | Look up email by Message-ID header (e.g. <abc123@example.com>). For threading/deduplication. | |
| groupByConversation | No | List conversations (threads) grouped by conversationId instead of individual emails. |