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
`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,
```

Instantly MCP Server