smartlead_get_campaign_mailbox_statistics
Retrieve detailed mailbox performance metrics for email campaigns, including delivery rates and engagement data, to monitor campaign effectiveness and optimize email marketing strategies.
Instructions
Fetch mailbox statistics for a campaign.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_id | Yes | ID of the campaign to fetch mailbox statistics for | |
| client_id | No | Client ID if the campaign is client-specific | |
| end_date | No | End date (must be used with start_date) | |
| limit | No | Maximum number of results to return (min 1, max 20) | |
| offset | No | Offset for pagination | |
| start_date | No | Start date (must be used with end_date) | |
| timezone | No | Timezone for the data (e.g., "America/Los_Angeles") |
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, ];