Gmail Search Emails
gmail_search_emailsSearch Gmail messages or whole conversations by query, labels, sender, recipient, subject, unread status, attachments, and age, with paginated results and optional Spam/Trash inclusion.
Instructions
Find Gmail messages, or with group_by_thread whole conversations, by a Gmail search query, labels (names or IDs) and helper filters (sender, recipient, subject, unread, attachments, age), ANDed together, a page at a time; Spam and Trash are left out unless include_spam_trash is true. Use gmail_get_mail_digest for a plain recent feed and gmail_check_mail_updates to poll for new mail since a saved checkpoint. Returns messages (id, thread_id, from, subject, date, snippet, unread, has_attachments, is_draft, is_sent) or threads (the same plus message_count), next_page_token, result_size_estimate and effective_query. Read bodies with gmail_read_emails or gmail_get_thread.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "gmail_search_emails"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Gmail search query in the same syntax as the Gmail search box, e.g. 'from:ana@example.com newer_than:7d has:attachment'. It is wrapped in parentheses and ANDed with the helper filters; with no query, labels or filters, all mail outside Spam and Trash matches. | |
| labels | No | Only mail that carries every one of these labels, given by name as shown in Gmail (e.g. 'Clients/Acme') or by ID; system labels such as INBOX or UNREAD match case-insensitively. An unknown or ambiguous name fails with not_found and the candidate labels. | |
| to_email | No | Recipient filter, added to the query as to:"<value>", e.g. 'team@example.com'. | |
| is_unread | No | When true, adds is:unread so only unread messages match; false adds nothing, so read mail matches too. | |
| from_email | No | Sender filter, added to the query as from:"<value>"; an address or part of a name, e.g. 'ana@example.com'. | |
| page_token | No | The next_page_token from the previous response of this same call; omit for the first page. | |
| max_results | No | Messages (or, with group_by_thread, conversations) per page, 1 to 500 (default 25); each hit is fetched separately, so large pages are slower. | |
| has_attachment | No | When true, adds has:attachment so only messages with attachments match; false adds nothing. | |
| group_by_thread | No | When true, returns conversations instead of messages: threads, each summarized by its newest message plus message_count. Default false returns individual messages. | |
| newer_than_days | No | Only mail from the last N days, 1 to 3650, translated to Gmail's newer_than:{N}d query operator. | |
| subject_contains | No | Phrase that must appear in the subject line, added to the query as subject:"<value>". | |
| include_spam_trash | No | Also return items in Spam and Trash; by default they are excluded. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of items in this response. | |
| threads | No | ||
| has_more | No | Whether another page is available. | |
| messages | No | ||
| fetched_at | No | RFC3339 time when this response was fetched. | |
| effective_query | No | ||
| next_page_token | No | Opaque token for the next page, or null. | |
| account_timezone | No | ||
| result_size_estimate | No |