search_emails
Locate specific emails in Gmail using advanced search queries to filter by sender, attachments, or other criteria, optimizing email retrieval efficiency.
Instructions
Search emails with advanced query
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| maxResults | No | Maximum number of emails to return (default: 10) | |
| query | Yes | Gmail search query (e.g., "from:example@gmail.com has:attachment") |
Implementation Reference
- src/index.ts:307-359 (handler)The main handler function for the 'search_emails' tool. It uses the Gmail API to list messages matching the provided query, fetches detailed headers (subject, from, date) for each, and returns them as JSON.
private async handleSearchEmails(args: any) { try { const maxResults = args?.maxResults || 10; const query = args?.query || ''; const response = await this.gmail.users.messages.list({ userId: 'me', maxResults, q: query, }); const messages = response.data.messages || []; const emailDetails = await Promise.all( messages.map(async (msg) => { const detail = await this.gmail.users.messages.get({ userId: 'me', id: msg.id!, }); const headers = detail.data.payload?.headers; const subject = headers?.find((h) => h.name === 'Subject')?.value || ''; const from = headers?.find((h) => h.name === 'From')?.value || ''; const date = headers?.find((h) => h.name === 'Date')?.value || ''; return { id: msg.id, subject, from, date, }; }) ); return { content: [ { type: 'text', text: JSON.stringify(emailDetails, null, 2), }, ], }; } catch (error: any) { return { content: [ { type: 'text', text: `Error fetching emails: ${error.message}`, }, ], isError: true, }; } } - src/index.ts:82-96 (schema)Input schema definition for the 'search_emails' tool, specifying required 'query' parameter and optional 'maxResults'.
inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Gmail search query (e.g., "from:example@gmail.com has:attachment")', required: true }, maxResults: { type: 'number', description: 'Maximum number of emails to return (default: 10)', }, }, required: ['query'] }, - src/index.ts:79-97 (registration)Tool registration in the ListTools response, including name, description, and input schema.
{ name: 'search_emails', description: 'Search emails with advanced query', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Gmail search query (e.g., "from:example@gmail.com has:attachment")', required: true }, maxResults: { type: 'number', description: 'Maximum number of emails to return (default: 10)', }, }, required: ['query'] }, }, - src/index.ts:232-233 (registration)Dispatcher case in CallToolRequestSchema handler that routes 'search_emails' calls to the handleSearchEmails function.
case 'search_emails': return await this.handleSearchEmails(request.params.arguments);