list-mail-messages
list-mail-messagesList, search, and filter Outlook email messages in the signed-in user's mailbox across all folders. Returns message metadata (subject, from, receivedDateTime, isRead, hasAttachments) plus a body preview.
Instructions
List, search, and filter Outlook email messages in the signed-in user's mailbox across all folders. Returns message metadata (subject, from, receivedDateTime, isRead, hasAttachments) plus a body preview. Use $search for keyword queries, $filter to narrow by sender/read state/date, $top to limit page size, and $select to trim fields.
💡 TIP: List read search my Outlook emails across folders. CRITICAL: When searching emails, the $search parameter value MUST be wrapped in double quotes. Format: $search="your search query here". Use KQL (Keyword Query Language) syntax to search specific properties: 'from:', 'subject:', 'body:', 'to:', 'cc:', 'bcc:', 'attachment:', 'hasAttachments:', 'importance:', 'received:', 'sent:'. Examples: $search="from:john@example.com" | $search="subject:meeting AND hasAttachments:true" | $search="body:urgent AND received>=2024-01-01" | $search="from:john AND importance:high". Remember: ALWAYS wrap the entire search expression in double quotes! Reference: https://learn.microsoft.com/en-us/graph/search-query-parameter IMPORTANT: Always use $select to limit returned fields and reduce response size. Recommended default: $select=id,subject,from,toRecipients,receivedDateTime,bodyPreview,isRead,hasAttachments. Use bodyPreview instead of body for listings. To read the full email body, use get-mail-message with the specific message id.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Page size (Graph $top). Start small (e.g. 5–15) so responses fit the model context; raise only if needed. Use $select to return fewer fields per item. For more rows, use @odata.nextLink from the response instead of a very large $top. | |
| skip | No | Items to skip for pagination. Not supported with $search. | |
| count | No | Set true to enable advanced query mode (ConsistencyLevel: eventual). Required for complex $filter on flag/flagStatus or contains(). The response then includes @odata.count, the total for the filtered collection, which can exceed the items returned when fetchAllPages hits its page/item cap. | |
| expand | No | Navigation properties to inline, e.g. attachments on a message or event. Only navigation properties can be expanded: expanding a non-navigation property such as a message body fails with "Parsing OData Select and Expand failed". Request ordinary fields with $select instead. Some APIs accept only one relationship per request, so prefer a single value. Some relationships support nested selection, e.g. children($select=id,name). | |
| filter | No | OData filter expression. Add $count=true for advanced filters (flag/flagStatus, contains()). Cannot combine with $search. | |
| search | No | KQL search query in one pair of double quotes; directory (users/groups) instead quotes each clause with no outer pair. Cannot combine with $filter. | |
| select | No | Comma-separated fields to return, e.g. id,subject,from,receivedDateTime | |
| orderby | No | Sort expression, e.g. receivedDateTime desc | |
| skiptoken | No | Next page: the @odata.nextLink from the previous response. Keep the other arguments the same. | |
| fetchAllPages | No | Follow @odata.nextLink and merge up to 100 pages into one response. Can return enormous payloads—only when the user explicitly needs a full export. Prefer a small $top first, then paginate or narrow with $filter/$search. | |
| includeHeaders | No | Include response headers (including ETag) in the response metadata | |
| excludeResponse | No | Exclude the full response body and only return success or failure indication | |
| includeHiddenMessages | No | Include Hidden Messages |