get_warmup_analytics
Analyze email warmup performance for accounts by retrieving metrics on deliverability and engagement over specified date ranges.
Instructions
Get warmup analytics for one or more accounts. API REQUIREMENT: The Instantly API expects an array of email addresses, even for a single account.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| emails | Yes | Array of email addresses to get warmup analytics for (1-100 emails). Use email addresses from list_accounts. | |
| end_date | No | End date (YYYY-MM-DD) - optional | |
| start_date | No | Start date (YYYY-MM-DD) - optional |
Implementation Reference
- src/handlers/tool-executor.ts:707-741 (handler)Core execution logic for get_warmup_analytics tool. Normalizes single email or array input, builds POST request body, calls Instantly API /accounts/warmup-analytics endpoint, and returns formatted MCP response.case 'get_warmup_analytics': { // Handle both single email and emails array for user convenience let emailsArray: string[] = []; if (args?.emails && Array.isArray(args.emails)) { emailsArray = args.emails; } else if (args?.email && typeof args.email === 'string') { emailsArray = [args.email]; } else { throw new McpError(ErrorCode.InvalidParams, 'Either "email" (string) or "emails" (array) is required'); } // Validate email array if (emailsArray.length === 0) { throw new McpError(ErrorCode.InvalidParams, 'At least one email address is required'); } console.error(`[Instantly MCP] get_warmup_analytics for emails: ${JSON.stringify(emailsArray)}`); // Use POST method with JSON body as per official API documentation const requestBody: any = { emails: emailsArray }; // Add optional date parameters to the body if provided if (args?.start_date) requestBody.start_date = args.start_date; if (args?.end_date) requestBody.end_date = args.end_date; console.error(`[Instantly MCP] POST body: ${JSON.stringify(requestBody, null, 2)}`); const result = await makeInstantlyRequest('/accounts/warmup-analytics', { method: 'POST', body: requestBody }, apiKey); return createMCPResponse(result); }
- src/tools/analytics-tools.ts:43-57 (schema)MCP tool registration definition including name, description, annotations, and inputSchema for get_warmup_analytics.{ name: 'get_warmup_analytics', title: 'Warmup Analytics', description: 'Get warmup metrics for account(s)', annotations: { readOnlyHint: true }, inputSchema: { type: 'object', properties: { emails: { type: 'array', items: { type: 'string' }, description: 'Account emails' }, email: { type: 'string', description: 'Single email (alternative)' }, start_date: { type: 'string', description: 'YYYY-MM-DD' }, end_date: { type: 'string', description: 'YYYY-MM-DD' } } } },
- src/validation.ts:293-302 (schema)Zod TypeScript schema (GetWarmupAnalyticsSchema) defining input validation rules for emails array (1-100), optional date ranges using shared EmailSchema and DateFormatSchema./** * Warmup analytics validation schema */ export const GetWarmupAnalyticsSchema = z.object({ emails: z.array(EmailSchema) .min(1, { message: 'At least one email address is required' }) .max(100, { message: 'Cannot specify more than 100 email addresses' }), start_date: DateFormatSchema.optional(), end_date: DateFormatSchema.optional() });
- src/validation.ts:687-688 (helper)Helper validation function that applies GetWarmupAnalyticsSchema to input args via generic validateWithSchema utility, throwing McpError on failure.export function validateWarmupAnalyticsData(args: unknown): z.infer<typeof GetWarmupAnalyticsSchema> { return validateWithSchema(GetWarmupAnalyticsSchema, args, 'get_warmup_analytics');
- src/validation.ts:821-821 (registration)Registration of the tool's validator in the central TOOL_VALIDATORS mapping object, enabling dynamic validation via validateToolParameters(toolName, args). Note: not directly called in handler but available system-wide.'get_warmup_analytics': validateWarmupAnalyticsData,