Get Statistics Overview
get_stats_overviewRetrieve comprehensive email statistics overview across multiple dimensions including date ranges, grouping options, and subuser data for SendGrid email analytics.
Instructions
Get a comprehensive overview of email statistics across multiple dimensions
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | Start date in YYYY-MM-DD format | |
| end_date | No | End date in YYYY-MM-DD format (defaults to today) | |
| aggregated_by | No | How to group the statistics | day |
| include_subusers | No | Include subuser statistics in the overview |
Implementation Reference
- src/tools/stats.ts:191-217 (handler)The main handler function for get_stats_overview, which fetches statistics from multiple SendGrid endpoints (global, browsers, clients, geo, mailbox providers) in parallel and returns a combined overview.
handler: async ({ start_date, end_date, aggregated_by, include_subusers }: { start_date: string; end_date?: string; aggregated_by?: string; include_subusers?: boolean }): Promise<ToolResult> => { const baseParams = `start_date=${start_date}${end_date ? `&end_date=${end_date}` : ''}${aggregated_by ? `&aggregated_by=${aggregated_by}` : ''}`; // Fetch multiple stats in parallel for comprehensive overview const [globalStats, browserStats, clientStats, geoStats, providerStats] = await Promise.all([ makeRequest(`https://api.sendgrid.com/v3/stats?${baseParams}`), makeRequest(`https://api.sendgrid.com/v3/browsers/stats?${baseParams}`), makeRequest(`https://api.sendgrid.com/v3/clients/stats?${baseParams}`), makeRequest(`https://api.sendgrid.com/v3/geo/stats?${baseParams}`), makeRequest(`https://api.sendgrid.com/v3/mailbox_providers/stats?${baseParams}`) ]); const overview = { period: { start_date, end_date: end_date || new Date().toISOString().split('T')[0], aggregated_by: aggregated_by || 'day' }, global_statistics: globalStats, browser_statistics: browserStats, client_statistics: clientStats, geographic_statistics: geoStats, mailbox_provider_statistics: providerStats }; return { content: [{ type: "text", text: JSON.stringify(overview, null, 2) }] }; }, - src/tools/stats.ts:184-189 (schema)Zod input schema defining parameters: start_date (required), end_date (optional), aggregated_by (optional, defaults to 'day'), include_subusers (optional, defaults to false).
inputSchema: { start_date: z.string().describe("Start date in YYYY-MM-DD format"), end_date: z.string().optional().describe("End date in YYYY-MM-DD format (defaults to today)"), aggregated_by: z.enum(["day", "week", "month"]).optional().default("day").describe("How to group the statistics"), include_subusers: z.boolean().optional().default(false).describe("Include subuser statistics in the overview"), }, - src/index.ts:20-23 (registration)MCP server registration loop that dynamically registers get_stats_overview (via allTools[name]) with its config and handler to the McpServer.
// Register all tools for (const [name, tool] of Object.entries(allTools)) { server.registerTool(name, tool.config as any, tool.handler as any); } - src/tools/index.ts:9-15 (registration)Aggregation of all tools including statsTools (which contains get_stats_overview) into allTools, imported and used for registration in src/index.ts.
export const allTools = { ...automationTools, ...campaignTools, ...contactTools, ...mailTools, ...miscTools, ...statsTools,