Smartlead Simplified MCP Server

Instructions

Implementation Reference

• src/handlers/statistics.ts:309-349 (handler)

  Core handler function that validates input parameters using isCampaignMailboxStatisticsParams, extracts campaign_id and query parameters, makes authenticated API call to Smartlead's /campaigns/{campaign_id}/mailbox-statistics endpoint with retry logic, and returns formatted JSON response or error message.

  async function handleCampaignMailboxStatistics(
    args: unknown,
    apiClient: AxiosInstance,
    withRetry: <T>(operation: () => Promise<T>, context: string) => Promise<T>
  ) {
    if (!isCampaignMailboxStatisticsParams(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid arguments for smartlead_get_campaign_mailbox_statistics'
      );
    }
  
    const { campaign_id, ...queryParams } = args;
  
    try {
      const response = await withRetry(
        async () => apiClient.get(`/campaigns/${campaign_id}/mailbox-statistics`, {
          params: queryParams
        }),
        'get campaign mailbox 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:156-194 (schema)

  Tool definition including name, description, category, and detailed inputSchema specifying parameters like campaign_id (required), client_id, offset, limit (1-20), start_date/end_date pair, and timezone.

  export const CAMPAIGN_MAILBOX_STATISTICS_TOOL: CategoryTool = {
    name: 'smartlead_get_campaign_mailbox_statistics',
    description: 'Fetch mailbox statistics for a campaign.',
    category: ToolCategory.CAMPAIGN_STATISTICS,
    inputSchema: {
      type: 'object',
      properties: {
        campaign_id: {
          type: 'number',
          description: 'ID of the campaign to fetch mailbox statistics for',
        },
        client_id: {
          type: 'string',
          description: 'Client ID if the campaign is client-specific',
        },
        offset: {
          type: 'number',
          description: 'Offset for pagination',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of results to return (min 1, max 20)',
        },
        start_date: {
          type: 'string',
          description: 'Start date (must be used with end_date)',
        },
        end_date: {
          type: 'string',
          description: 'End date (must be used with start_date)',
        },
        timezone: {
          type: 'string',
          description: 'Timezone for the data (e.g., "America/Los_Angeles")',
        },
      },
      required: ['campaign_id'],
    },
  };

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

  Registers the statisticsTools array (which includes this tool) to the toolRegistry if campaignStatistics category is enabled by license/configuration.

  if (enabledCategories.campaignStatistics) {
    toolRegistry.registerMany(statisticsTools);
  }

• src/handlers/statistics.ts:17-54 (handler)

  Category-level dispatcher function that routes 'smartlead_get_campaign_mailbox_statistics' calls to the specific handleCampaignMailboxStatistics handler.

  export async function handleStatisticsTool(
    toolName: string,
    args: unknown,
    apiClient: AxiosInstance,
    withRetry: <T>(operation: () => Promise<T>, context: string) => Promise<T>
  ) {
    switch (toolName) {
      case 'smartlead_get_campaign_statistics': {
        return handleCampaignStatistics(args, apiClient, withRetry);
      }
      case 'smartlead_get_campaign_statistics_by_date': {
        return handleCampaignStatisticsByDate(args, apiClient, withRetry);
      }
      case 'smartlead_get_warmup_stats_by_email': {
        return handleWarmupStatsByEmail(args, apiClient, withRetry);
      }
      case 'smartlead_get_campaign_top_level_analytics': {
        return handleCampaignTopLevelAnalytics(args, apiClient, withRetry);
      }
      case 'smartlead_get_campaign_top_level_analytics_by_date': {
        return handleCampaignTopLevelAnalyticsByDate(args, apiClient, withRetry);
      }
      case 'smartlead_get_campaign_lead_statistics': {
        return handleCampaignLeadStatistics(args, apiClient, withRetry);
      }
      case 'smartlead_get_campaign_mailbox_statistics': {
        return handleCampaignMailboxStatistics(args, apiClient, withRetry);
      }
      case 'smartlead_download_campaign_data': {
        return handleDownloadCampaignData(args, apiClient, withRetry);
      }
      case 'smartlead_view_download_statistics': {
        return handleViewDownloadStatistics(args);
      }
      default:
        throw new Error(`Unknown statistics tool: ${toolName}`);
    }
  }

• src/tools/statistics.ts:250-260 (registration)

  Includes the CAMPAIGN_MAILBOX_STATISTICS_TOOL in the statisticsTools export array used for bulk registration.

  export const statisticsTools: CategoryTool[] = [
    CAMPAIGN_STATISTICS_TOOL,
    CAMPAIGN_STATISTICS_BY_DATE_TOOL,
    WARMUP_STATS_BY_EMAIL_TOOL,
    CAMPAIGN_TOP_LEVEL_ANALYTICS_TOOL,
    CAMPAIGN_TOP_LEVEL_ANALYTICS_BY_DATE_TOOL,
    CAMPAIGN_LEAD_STATISTICS_TOOL,
    CAMPAIGN_MAILBOX_STATISTICS_TOOL,
    DOWNLOAD_CAMPAIGN_DATA_TOOL,
    VIEW_DOWNLOAD_STATISTICS_TOOL,
  ];