get_stats_by_country
Retrieve email performance statistics grouped by geographic location to analyze regional engagement patterns and optimize email marketing strategies.
Instructions
Retrieve email statistics grouped by geographic location
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| aggregated_by | No | How to group the statistics | day |
| country | No | ISO 3166-1 alpha-2 country code to filter by | |
| end_date | No | End date in YYYY-MM-DD format (defaults to today) | |
| start_date | Yes | Start date in YYYY-MM-DD format | |
| state | No | State or province to filter by |
Implementation Reference
- src/tools/stats.ts:104-114 (handler)The handler function that builds the SendGrid /v3/geo/stats API request URL with provided parameters (dates, aggregation, country, state filters) and returns the JSON stats.handler: async ({ start_date, end_date, aggregated_by, country, state }: { start_date: string; end_date?: string; aggregated_by?: string; country?: string; state?: string }): Promise<ToolResult> => { let url = `https://api.sendgrid.com/v3/geo/stats?start_date=${start_date}`; if (end_date) url += `&end_date=${end_date}`; if (aggregated_by) url += `&aggregated_by=${aggregated_by}`; if (country) url += `&country=${encodeURIComponent(country)}`; if (state) url += `&state=${encodeURIComponent(state)}`; const result = await makeRequest(url); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }; }, },
- src/tools/stats.ts:96-102 (schema)Zod schema for tool inputs: required start_date, optional end_date, aggregated_by (day|week|month default day), country, state.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"), country: z.string().optional().describe("ISO 3166-1 alpha-2 country code to filter by"), state: z.string().optional().describe("State or province to filter by"), },
- src/tools/index.ts:6-17 (registration)Includes statsTools (containing get_stats_by_country) in the allTools export via object spread, making it available for MCP registration.import { statsTools } from "./stats.js"; import { templateTools } from "./templates.js"; export const allTools = { ...automationTools, ...campaignTools, ...contactTools, ...mailTools, ...miscTools, ...statsTools, ...templateTools, };
- src/index.ts:21-23 (registration)Generic registration loop that registers get_stats_by_country (from allTools) to the MCP server.for (const [name, tool] of Object.entries(allTools)) { server.registerTool(name, tool.config as any, tool.handler as any); }