How to Find Emails

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 searches across subject, body, and other fields on work/school Microsoft 365 accounts. On personal Outlook.com accounts Graph $search is unavailable, so query falls back to a subject substring match (every word must appear in the subject) — precise, but it does not read message bodies. Use searchExpression when you need body content there.

Personal accounts: Free-text query search uses Microsoft’s $search API, which has limited support on personal Outlook.com accounts. Outlook Assistant handles this automatically — if $search returns no results, 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 query searches use Microsoft’s $search API, 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 $filter which works consistently across both personal and work accounts.

to is 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 pair to with receivedAfter/receivedBefore to 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.

Personal accounts: searchAllFolders uses the same $search API, so pair it with a plain-text query (which falls back to filters) or the structured filters for the most reliable coverage. Field-scoped searchExpression works too as of v3.10.0 — from:/to:/subject: expressions are translated to the equivalent filters and retried — but expressions using AND/OR, grouping or other field prefixes are not translated there.

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 always be empty — if it isn’t, the results are wider than what you asked for.

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.

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 across all fields (subject-only on personal accounts — see above)	"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 + receivedAfter for the most targeted searches
• To search a shared mailbox, add sharedMailbox — every mode works, including folder paths and searchAllFolders. It needs the opt-in OUTLOOK_SHARED_MAILBOX setting; see Access Shared Mailboxes
• Personal accounts (Outlook.com): Outlook Assistant automatically tries multiple search strategies if $search is unavailable, but subject, 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