get_mailbox_stats
Read-onlyIdempotent
Retrieve unread counts and total email statistics for a specific mailbox or all mailboxes to get a quick summary of mailbox volume without listing individual messages.
Instructions
Get statistics such as unread counts and total emails for a mailbox or across the account. Use when the user wants a summary of mailbox volume or unread counts rather than individual messages. Do not use for listing messages themselves.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mailboxId | No | ID of the mailbox (optional, defaults to all mailboxes) |
Implementation Reference
- src/mcp-server.ts:358-362 (handler)Handler for the 'get_mailbox_stats' tool - invokes client.getMailboxStats(mailboxId) and returns the result as JSON text.
case 'get_mailbox_stats': { const { mailboxId } = args as any; const stats = await client.getMailboxStats(mailboxId); return { content: [{ type: 'text', text: JSON.stringify(stats, null, 2) }] }; } - src/jmap-client.ts:1079-1110 (helper)Core implementation of getMailboxStats - calls JMAP Mailbox/get for a specific mailbox or aggregates stats across all mailboxes.
async getMailboxStats(mailboxId?: string): Promise<any> { const session = await this.getSession(); if (mailboxId) { // Get stats for specific mailbox const request: JmapRequest = { using: ['urn:ietf:params:jmap:core', 'urn:ietf:params:jmap:mail'], methodCalls: [ ['Mailbox/get', { accountId: session.accountId, ids: [mailboxId], properties: ['id', 'name', 'role', 'totalEmails', 'unreadEmails', 'totalThreads', 'unreadThreads'] }, 'mailbox'] ] }; const response = await this.makeRequest(request); return this.getListResult(response, 0)[0]; } else { // Get stats for all mailboxes const mailboxes = await this.getMailboxes(); return mailboxes.map(mb => ({ id: mb.id, name: mb.name, role: mb.role, totalEmails: mb.totalEmails || 0, unreadEmails: mb.unreadEmails || 0, totalThreads: mb.totalThreads || 0, unreadThreads: mb.unreadThreads || 0 })); } } - src/tool-definitions.ts:677-693 (schema)Schema/definition for the get_mailbox_stats tool - describes input parameters (optional mailboxId) and usage guidance.
'get_mailbox_stats', 'Get Mailbox Stats', description( 'Get statistics such as unread counts and total emails for a mailbox or across the account.', 'Use when the user wants a summary of mailbox volume or unread counts rather than individual messages.', 'Do not use for listing messages themselves.', ), { type: 'object', properties: { mailboxId: { type: 'string', description: 'ID of the mailbox (optional, defaults to all mailboxes)', }, }, }, ), - src/mcp-server.ts:416-417 (registration)Registration of 'get_mailbox_stats' as an available function in the email tool capabilities list.
'get_mailbox_stats', 'get_account_summary', 'bulk_mark_read', 'bulk_move', 'bulk_delete', 'add_labels', 'remove_labels', 'bulk_add_labels', 'bulk_remove_labels',