search_messages
Read-onlyIdempotent
Search for email messages in any folder using filters like sender, subject, date, or read status; returns matching summaries sorted by newest first.
Instructions
Search for messages in a folder by various criteria (sender, subject, date, flags). Returns matching message summaries sorted by date (newest first). Note: recently sent or received messages may take a few seconds to become searchable by subject or body due to server-side indexing delays; searching by 'from' is typically immediate. A non-selectable namespace container (e.g. Folders/Labels) is rejected with an actionable error rather than returning no matches.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | Folder to search in (default: INBOX) | INBOX |
| from | No | Filter by sender email address or name | |
| to | No | Filter by recipient email address | |
| subject | No | Filter by subject (substring match) | |
| body | No | Filter by body content (substring match) | |
| since | No | Messages since this date (YYYY-MM-DD, inclusive — includes messages on this date) | |
| before | No | Messages before this date (YYYY-MM-DD, exclusive — messages strictly before this date) | |
| seen | No | Filter by read status: true=read, false=unread | |
| flagged | No | Filter by flagged/starred status | |
| larger | No | Match messages larger than this many bytes | |
| smaller | No | Match messages smaller than this many bytes | |
| listId | No | Filter by List-Id header (substring match) — useful for newsletter cleanup | |
| hasAttachment | No | Match messages that have attachments. Approximation: sets a 5 KB size floor and post-filters by body structure. Capped at 500 candidates. | |
| attachmentName | No | Case-insensitive substring filter on attachment filenames (e.g. "invoice", ".pdf"). Implies hasAttachment. | |
| attachmentType | No | Case-insensitive MIME-type prefix filter on attachments (e.g. "application/pdf", "image/"). Implies hasAttachment. | |
| limit | No | Maximum results to return (default: 20, max: 100) | |
| includeSnippet | No | Append a ~200-char body preview to each row. Adds one fetch per message; default off. |