Get Email Statistics by Subuser

Instructions

Implementation Reference

• src/tools/stats.ts:159-178 (handler)

  The handler function for get_subuser_stats. It calls the SendGrid API at /v3/subusers/stats with subusers, start_date, end_date, and aggregated_by parameters.

  get_subuser_stats: {
    config: {
      title: "Get Email Statistics by Subuser",
      description: "Retrieve email statistics for specific subusers",
      inputSchema: {
        subusers: z.string().describe("Comma-separated list of subuser names to retrieve stats for"),
        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"),
      },
    },
    handler: async ({ subusers, start_date, end_date, aggregated_by }: { subusers: string; start_date: string; end_date?: string; aggregated_by?: string }): Promise<ToolResult> => {
      let url = `https://api.sendgrid.com/v3/subusers/stats?subusers=${encodeURIComponent(subusers)}&start_date=${start_date}`;
      if (end_date) url += `&end_date=${end_date}`;
      if (aggregated_by) url += `&aggregated_by=${aggregated_by}`;
      
      const result = await makeRequest(url);
      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
    },
  },

• src/tools/stats.ts:163-168 (schema)

  Input schema for get_subuser_stats: subusers (string), start_date (string), end_date (optional string), aggregated_by (enum day/week/month, defaults to day).

  inputSchema: {
    subusers: z.string().describe("Comma-separated list of subuser names to retrieve stats for"),
    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"),
  },

• src/index.ts:20-23 (registration)

  Tools are registered via the allTools export. server.registerTool(name, config, handler) is called for each tool including get_subuser_stats.

  // 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-17 (registration)

  allTools object collects all tool definitions from statsTools (which includes get_subuser_stats) and exports them for registration.

  export const allTools = {
    ...automationTools,
    ...campaignTools,
    ...contactTools,
    ...mailTools,
    ...miscTools,
    ...statsTools,
    ...templateTools,
  };

• src/shared/api.ts:3-18 (helper)

  The makeRequest helper function used by the handler to make authenticated HTTP requests to the SendGrid API.

  export async function makeRequest(url: string, options: RequestInit = {}): Promise<any> {
    const response = await fetch(url, {
      headers: {
        ...getAuthHeaders(),
        ...options.headers,
      },
      ...options,
    });
  
    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(`SendGrid API error (${response.status}): ${errorText}`);
    }
  
    return response.json();
  }