list_messages
List recent messages from an email folder, sorted by date or UID. Returns subject, sender, date, and flags with optional body preview.
Instructions
List recent messages from an email folder, sorted by date (newest first). Returns subject, sender, date, and flags for each message. A non-selectable namespace container (e.g. Folders/Labels) is rejected with an actionable error rather than returning an empty list.
Pagination note: the default date sort is paginated by a UID cursor (beforeUid). In folders where UID order disagrees with date order — All Mail, or any folder holding moved messages — page boundaries can skip or reorder messages relative to strict date order. For exact, skip-free paging set sortByUid: true (orders by UID = arrival order, newest first); for a precise date window use search_messages with since/before.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | Folder path to list messages from (default: INBOX) | INBOX |
| limit | No | Maximum number of messages to return (default: 20, max: 100) | |
| beforeUid | No | Fetch messages with UIDs before this value (for pagination). Pass the smallest UID from the previous page. | |
| includeSnippet | No | Append a ~200-char body preview to each row. Adds one fetch per message; default off. | |
| sortByUid | No | Order by UID descending (arrival order, newest first) instead of by date. Makes `beforeUid` pagination exact — no skips or duplicates at page boundaries, even in All Mail or folders with moved messages. Default false (date sort). |