How to Find Emails
Search your inbox by sender, subject, date range, or keywords — including across all folders.
Search and filter your emails to find exactly what you need. With no search terms, Outlook Assistant lists your most recent messages.
List Recent Emails
Ask your AI assistant to show your latest emails:
“Show me my recent emails”
tool: search-emails
With no parameters, this returns the 25 most recent emails from your inbox.
Search by Sender
“Find emails from sarah@company.com”
tool: search-emails
params:
from: "sarah@company.com"
You can also search by partial name:
tool: search-emails
params:
from: "Sarah"
Search by Subject
“Find emails about the quarterly report”
tool: search-emails
params:
subject: "quarterly report"
The subject parameter uses an OData filter (contains(subject, ...)) which works reliably on both personal and work/school accounts.
Search by Keywords
“Search my emails for budget approval”
tool: search-emails
params:
query: "budget approval"
The query parameter goes to Graph $search, which matches subject, body and sender on both work/school Microsoft 365 and personal Outlook.com accounts. $search takes no other filters, so a date or boolean window is applied to its results, sorted newest first (_meta.searchMetadata.orderedWithinPage), reading at most 250 messages; partialCoverage says when more remained. With from, to or subject, those go to Graph as a filter instead and query is matched against each result’s subject, preview and sender.
Personal accounts: Microsoft’s
$searchAPI takes no other filters. Outlook Assistant handles this automatically — if$searchfails or nothing passes your other filters, it progressively falls back to OData filters (from,subject,to), then boolean filters, then recent message listing. For the most direct results on personal accounts, use the structured filter parameters below. See Account Compatibility for details.
Filter by Date Range
“Show me emails from January 2026”
tool: search-emails
params:
receivedAfter: "2026-01-01"
receivedBefore: "2026-02-01"
Dates use ISO 8601 format (YYYY-MM-DD or full YYYY-MM-DDTHH:MM:SSZ).
Find Unread Emails Only
“Show me my unread emails”
tool: search-emails
params:
unreadOnly: true
Find Emails with Attachments
“Find emails with attachments from this month”
tool: search-emails
params:
hasAttachments: true
receivedAfter: "2026-03-01"
Search a Specific Folder
By default, searches look in the inbox. To search another folder:
“Show me my sent emails to john@company.com”
tool: search-emails
params:
folder: "sentitems"
to: "john@company.com"
Common folder names: inbox, sentitems, drafts, deleteditems, archive, junkemail.
You can also search custom folders by display name, including nested folders addressed with a / path (v3.9.0) — each segment is resolved from its parent:
tool: search-emails
params:
folder: "Projects/Client A"
subject: "proposal"
Searching Sent Items
When searching Sent Items, use to: to filter by recipient (since you are the sender of all emails in Sent Items):
tool: search-emails
params:
folder: "sentitems"
to: "client@example.com"
Other useful filters for Sent Items:
tool: search-emails
params:
folder: "sentitems"
subject: "invoice"
receivedAfter: "2026-01-01"
hasAttachments: true
Personal accounts: Free-text
querysearches use Microsoft’s$searchAPI, which has limited support on personal Outlook.com accounts. Use structured filters (subject,receivedAfter,hasAttachments) for the most reliable results in any folder. These use$filterwhich works consistently across both personal and work accounts.
tois the exception: personal accounts reject the server-side recipient filter, so it is matched locally over the 500 most recent messages (OUTLOOK_SEARCH_SCAN_LIMIT, max 5000). On a large mailbox that excludes older mail, so pairtowithreceivedAfter/receivedBeforeto reach further back. Since v3.11.1 the response says so whenever that scan was truncated, whether or not it matched.
Search Across All Folders
“Search all my folders for the contract document”
tool: search-emails
params:
query: "contract document"
searchAllFolders: true
Cross-folder search is a strict superset of an inbox-only search — it never returns fewer results than searching the inbox alone (v3.9.0). Multi-word queries also match when the words aren’t adjacent in the subject, and if nothing turns up the result explicitly reports that it searched all folders.
$searchand all folders: aqueryorsearchExpressionanswered by Graph$searchacross all folders leaves out Deleted Items and Junk Email (measured on a personal mailbox); name the folder to search inside one of them. The structured filters (from,to,subject, dates) do cover every folder. Since v3.14.2 a booleansearchExpression(invoice OR receipt,subject:… AND received>=…) works on personal accounts; one made only offrom:/to:/subject:terms is answered by filters there, as before.
Combine Filters
Filters stack — use multiple parameters together:
“Find unread emails from Sarah with attachments received this week”
tool: search-emails
params:
from: "Sarah"
unreadOnly: true
hasAttachments: true
receivedAfter: "2026-02-24"
Every filter you supply is honoured. If Microsoft Graph rejects a combined filter, Outlook Assistant applies the remaining terms locally rather than returning the broader single-filter result set, and reports anything it could not honour in _meta.searchMetadata.droppedFilters (v3.10.0). That field should be empty — if it isn’t, the results are wider than what you asked for. The one expected case is a date or boolean filter passed with a raw searchExpression (#329).
Control the Number of Results
tool: search-emails
params:
count: 10
| Mode | Default count | Maximum |
|---|---|---|
| List (no query) | 25 | 50 |
| Search | 10 | 50 |
There is no page cursor. When the result says more emails are available, raise count (up to 50) or narrow the date range with receivedAfter/receivedBefore. A raw searchExpression ignores those two parameters (the response lists them in droppedFilters), so put the date in the expression instead: invoice AND received>=2026-01-01.

Track Inbox Changes (Delta Sync)
Monitor your inbox for new, modified, or deleted emails since your last check:
“Check for new emails since my last sync”
tool: search-emails
params:
deltaMode: true
On the first call, this returns current emails and a deltaToken. A large folder arrives over several pages (maxResults per page, 1–200, default 100): while a page returns a continuation token, pass it back with the same maxResults until a delta token is returned. Pass that delta token on subsequent calls to get only changes:
tool: search-emails
params:
deltaMode: true
deltaToken: "previous-token-here"
Delta sync is useful for inbox monitoring workflows, audit trails, and notification triggers. See Monitor Your Inbox with Delta Sync for agent integration patterns.
Parameter Reference
| Parameter | What it does | Example |
|---|---|---|
query | Free-text search over subject, body and sender (see above for how it combines with other filters) | "budget approval" |
from | Filter by sender email or name | "sarah@company.com" |
to | Filter by recipient | "team@company.com" |
subject | Filter by subject line | "quarterly report" |
folder | Which folder to search | "sentitems" |
unreadOnly | Only unread messages | true |
hasAttachments | Only messages with attachments | true |
receivedAfter | Received after this date (ISO 8601) | "2026-01-01" |
receivedBefore | Received before this date | "2026-02-01" |
searchAllFolders | Search every folder | true |
count | Number of results to return | 10 |
searchExpression | Raw Graph $search expression for advanced queries (formerly kqlQuery) — see the KQL Search Reference for personal-account support | "subject:\"quarterly report\"" |
outputVerbosity | Detail level: minimal, standard, full | "minimal" |
sharedMailbox | Search a shared mailbox instead of your own (alias email; opt-in, work/school only) | "support@company.com" |
Tips
- No query parameters = list mode (most recent emails first)
- Use
outputVerbosity: "minimal"when you just need subject lines and dates - For advanced queries, see the KQL Search Reference
- Combine
from+receivedAfterfor the most targeted searches - To search a shared mailbox, add
sharedMailbox— every mode works, includingfolderpaths andsearchAllFolders. It needs the opt-inOUTLOOK_SHARED_MAILBOXsetting; see Access Shared Mailboxes - Personal accounts (Outlook.com): Outlook Assistant automatically tries multiple search strategies if
$searchfails or nothing passes your filters, butsubject,from,to, and date range filters give the most direct results. See Account Compatibility
Related
- Read Email Threads — read an email after finding it
- Export Emails — save search results to disk
- KQL Search Reference — advanced query patterns
- Tools Reference — search-emails