smartlead_get_campaign_statistics

Instructions

Implementation Reference

• src/handlers/statistics.ts:57-95 (handler)

  Core handler function that validates input parameters, makes authenticated API request to fetch campaign statistics, and formats the response as MCP content or error.

  async function handleCampaignStatistics(
    args: unknown,
    apiClient: AxiosInstance,
    withRetry: <T>(operation: () => Promise<T>, context: string) => Promise<T>
  ) {
    if (!isCampaignStatisticsParams(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid arguments for smartlead_get_campaign_statistics'
      );
    }
  
    const { campaign_id, ...queryParams } = args;
  
    try {
      const response = await withRetry(
        async () => apiClient.get(`/campaigns/${campaign_id}/statistics`, { params: queryParams }),
        'get campaign statistics'
      );
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(response.data, null, 2),
          },
        ],
        isError: false,
      };
    } catch (error: any) {
      return {
        content: [{ 
          type: 'text', 
          text: `API Error: ${error.response?.data?.message || error.message}` 
        }],
        isError: true,
      };
    }
  }

• src/tools/statistics.ts:4-42 (schema)

  JSON Schema definition for the tool input parameters, including descriptions and validation rules.

  export const CAMPAIGN_STATISTICS_TOOL: CategoryTool = {
    name: 'smartlead_get_campaign_statistics',
    description: 'Fetch campaign statistics using the campaign\'s ID.',
    category: ToolCategory.CAMPAIGN_STATISTICS,
    inputSchema: {
      type: 'object',
      properties: {
        campaign_id: {
          type: 'number',
          description: 'ID of the campaign to fetch statistics for',
        },
        offset: {
          type: 'number',
          description: 'Offset for pagination',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of statistics to return',
        },
        email_sequence_number: {
          type: 'string',
          description: 'Email sequence number to filter by (e.g., "1,2,3,4")',
        },
        email_status: {
          type: 'string',
          description: 'Email status to filter by (e.g., "opened", "clicked", "replied", "unsubscribed", "bounced")',
        },
        sent_time_start_date: {
          type: 'string',
          description: 'Filter by sent time greater than this date (e.g., "2023-10-16 10:33:02.000Z")',
        },
        sent_time_end_date: {
          type: 'string',
          description: 'Filter by sent time less than this date (e.g., "2023-10-16 10:33:02.000Z")',
        },
      },
      required: ['campaign_id'],
    },
  };

• src/index.ts:211-214 (registration)

  Registers the array of statistics tools (including smartlead_get_campaign_statistics schema) into the central ToolRegistry based on feature configuration.

  // Register campaign statistics tools if enabled
  if (enabledCategories.campaignStatistics) {
    toolRegistry.registerMany(statisticsTools);
  }

• src/index.ts:352-353 (registration)

  Dispatches tool calls in CAMPAIGN_STATISTICS category to the statistics handler function based on tool name.

  case ToolCategory.CAMPAIGN_STATISTICS:
    return await handleStatisticsTool(name, toolArgs, apiClient, withRetry);

• src/types/statistics.ts:74-116 (helper)

  Type guard function for runtime validation of input parameters matching the tool schema, used in the handler.

  export function isCampaignStatisticsParams(args: unknown): args is CampaignStatisticsParams {
    if (typeof args !== 'object' || args === null) {
      return false;
    }
  
    const params = args as CampaignStatisticsParams;
    
    if (typeof params.campaign_id !== 'number') {
      return false;
    }
    
    // Optional offset must be a number if present
    if (params.offset !== undefined && typeof params.offset !== 'number') {
      return false;
    }
    
    // Optional limit must be a number if present
    if (params.limit !== undefined && typeof params.limit !== 'number') {
      return false;
    }
    
    // Optional email_sequence_number must be a string if present
    if (params.email_sequence_number !== undefined && typeof params.email_sequence_number !== 'string') {
      return false;
    }
    
    // Optional email_status must be a string if present
    if (params.email_status !== undefined && typeof params.email_status !== 'string') {
      return false;
    }
    
    // Optional sent_time_start_date must be a string if present
    if (params.sent_time_start_date !== undefined && typeof params.sent_time_start_date !== 'string') {
      return false;
    }
    
    // Optional sent_time_end_date must be a string if present
    if (params.sent_time_end_date !== undefined && typeof params.sent_time_end_date !== 'string') {
      return false;
    }
    
    return true;
  }