get_warmup_analytics

Instructions

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,