Get Email Statistics by Country and State/Province
get_stats_by_countryRetrieve email statistics grouped by geographic location to analyze campaign performance across countries and regions.
Instructions
Retrieve email statistics grouped by geographic location
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 |
| country | No | ISO 3166-1 alpha-2 country code to filter by | |
| state | No | State or province to filter by |
Implementation Reference
- src/tools/stats.ts:104-114 (handler)The handler function constructs the SendGrid API URL for /v3/geo/stats with parameters for date range, aggregation, country, and state filters, calls makeRequest, and returns the JSON-formatted 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-based input schema validating the tool parameters: required start_date (YYYY-MM-DD), optional end_date, aggregated_by (day/week/month default day), country (ISO code), and state/province.
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/index.ts:21-23 (registration)MCP server registration loop that iterates over allTools (including get_stats_by_country) and calls server.registerTool for each, passing name, config, and handler.
for (const [name, tool] of Object.entries(allTools)) { server.registerTool(name, tool.config as any, tool.handler as any); }