Instantly MCP Server

Instructions

Implementation Reference

• src/handlers/tool-executor.ts:663-705 (handler)

  The core handler implementation for the 'update_account' tool. Builds a partial update object from input arguments (first_name, last_name, warmup config, daily_limit, sending_gap, tracking domain settings, etc.) and performs a PATCH request to the Instantly API endpoint `/accounts/{email}`.

  case 'update_account': {
    console.error('[Instantly MCP] 🔧 Executing update_account...');
  
    if (!args?.email) {
      throw new McpError(ErrorCode.InvalidParams, 'email is required');
    }
  
    // Build account update data with all provided parameters (excluding email from body)
    const updateData: any = {};
  
    // Add all optional parameters if provided
    if (args.first_name !== undefined) updateData.first_name = args.first_name;
    if (args.last_name !== undefined) updateData.last_name = args.last_name;
    if (args.warmup !== undefined) updateData.warmup = args.warmup;
    if (args.daily_limit !== undefined) updateData.daily_limit = args.daily_limit;
    if (args.tracking_domain_name !== undefined) updateData.tracking_domain_name = args.tracking_domain_name;
    if (args.tracking_domain_status !== undefined) updateData.tracking_domain_status = args.tracking_domain_status;
    if (args.enable_slow_ramp !== undefined) updateData.enable_slow_ramp = args.enable_slow_ramp;
    if (args.inbox_placement_test_limit !== undefined) updateData.inbox_placement_test_limit = args.inbox_placement_test_limit;
    if (args.sending_gap !== undefined) updateData.sending_gap = args.sending_gap;
    if (args.skip_cname_check !== undefined) updateData.skip_cname_check = args.skip_cname_check;
    if (args.remove_tracking_domain !== undefined) updateData.remove_tracking_domain = args.remove_tracking_domain;
  
    console.error(`[Instantly MCP] 📤 Updating account with data: ${JSON.stringify(updateData, null, 2)}`);
  
    const result = await makeInstantlyRequest(`/accounts/${encodeURIComponent(args.email)}`, {
      method: 'PATCH',
      body: updateData
    }, apiKey);
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            success: true,
            account: result,
            message: 'Account updated successfully'
          }, null, 2),
        },
      ],
    };
  }

• src/tools/account-tools.ts:67-109 (registration)

  Tool registration/definition including name, description, annotations, and detailed inputSchema used by MCP server.

  {
    name: 'update_account',
    title: 'Update Account',
    description: 'Update account settings (partial). Supports name, warmup, daily_limit, sending_gap, tracking_domain.',
    annotations: { destructiveHint: false },
    inputSchema: {
      type: 'object',
      properties: {
        email: { type: 'string', description: 'Account to update' },
        first_name: { type: 'string' },
        last_name: { type: 'string' },
        warmup: {
          type: 'object',
          properties: {
            limit: { type: 'number' },
            advanced: {
              type: 'object',
              properties: {
                warm_ctd: { type: 'boolean' },
                open_rate: { type: 'number' },
                important_rate: { type: 'number' },
                read_emulation: { type: 'boolean' },
                spam_save_rate: { type: 'number' },
                weekday_only: { type: 'boolean' }
              }
            },
            warmup_custom_ftag: { type: 'string' },
            increment: { type: 'string' },
            reply_rate: { type: 'number' }
          }
        },
        daily_limit: { type: 'number' },
        sending_gap: { type: 'number', description: 'Minutes between emails (0-1440)' },
        enable_slow_ramp: { type: 'boolean' },
        tracking_domain_name: { type: 'string' },
        tracking_domain_status: { type: 'string' },
        skip_cname_check: { type: 'boolean' },
        remove_tracking_domain: { type: 'boolean' },
        inbox_placement_test_limit: { type: 'number' }
      },
      required: ['email']
    }
  },

• src/validation.ts:424-725 (schema)

  Zod schema (UpdateAccountSchema) and validator function (validateUpdateAccountData) for input validation of update_account tool arguments.

  export const UpdateAccountSchema = z.object({
    email: EmailSchema,
    first_name: z.string().optional(),
    last_name: z.string().optional(),
    warmup: z.object({
      limit: z.number().optional(),
      advanced: z.object({
        warm_ctd: z.boolean().optional(),
        open_rate: z.number().optional(),
        important_rate: z.number().optional(),
        read_emulation: z.boolean().optional(),
        spam_save_rate: z.number().optional(),
        weekday_only: z.boolean().optional()
      }).optional(),
      warmup_custom_ftag: z.string().optional(),
      increment: z.string().optional(),
      reply_rate: z.number().optional()
    }).optional(),
    daily_limit: z.number().int().min(1).max(1000).nullable().optional(),
    tracking_domain_name: z.string().nullable().optional(),
    tracking_domain_status: z.string().nullable().optional(),
    enable_slow_ramp: z.boolean().nullable().optional(),
    inbox_placement_test_limit: z.number().nullable().optional(),
    sending_gap: z.number().min(0).max(1440).optional(),
    skip_cname_check: z.boolean().optional(),
    remove_tracking_domain: z.boolean().optional()
  });
  
  /**
   * Lead creation validation schema - Updated to match Instantly.ai API v2 specification
   */
  export const CreateLeadSchema = z.object({
    // Core lead information
    campaign: z.string().optional(),
    email: z.string().email().optional(),
    first_name: z.string().optional(),
    last_name: z.string().optional(),
    company_name: z.string().optional(),
    phone: z.string().optional(),
    website: z.string().url().optional(),
    personalization: z.string().optional(),
  
    // Advanced parameters
    lt_interest_status: z.number().int().min(-3).max(4).optional(),
    pl_value_lead: z.string().optional(),
    list_id: z.string().optional(),
    assigned_to: z.string().optional(),
  
    // Skip conditions
    skip_if_in_workspace: z.boolean().optional(),
    skip_if_in_campaign: z.boolean().optional(),
    skip_if_in_list: z.boolean().optional(),
  
    // Verification and blocklist
    blocklist_id: z.string().optional(),
    verify_leads_for_lead_finder: z.boolean().optional(),
    verify_leads_on_import: z.boolean().optional(),
  
    // Custom variables
    custom_variables: z.record(z.string(), z.any()).optional()
  });
  
  /**
   * Update lead validation schema - Updated to match Instantly.ai API v2 specification
   */
  export const UpdateLeadSchema = z.object({
    lead_id: z.string().min(1, { message: 'Lead ID cannot be empty' }),
    personalization: z.string().optional(),
    website: z.string().url().optional(),
    last_name: z.string().optional(),
    first_name: z.string().optional(),
    company_name: z.string().optional(),
    phone: z.string().optional(),
    lt_interest_status: z.number().int().min(-3).max(4).optional(),
    pl_value_lead: z.string().optional(),
    assigned_to: z.string().optional(),
    custom_variables: z.record(z.string(), z.any()).optional()
  });
  
  /**
   * List leads validation schema
   */
  export const ListLeadsSchema = z.object({
    campaign_id: z.string().optional(),
    list_id: z.string().optional(),
    status: z.string().optional(),
    limit: z.number().int().min(1).max(100).optional(),
    starting_after: z.string().optional()
  });
  
  /**
   * Create lead list validation schema - Updated to match Instantly.ai API v2 specification
   */
  export const CreateLeadListSchema = z.object({
    name: z.string().min(1, { message: 'Lead list name cannot be empty' }),
    has_enrichment_task: z.boolean().optional(),
    owned_by: z.string().optional()
  });
  
  /**
   * List lead lists validation schema
   */
  export const ListLeadListsSchema = z.object({
    limit: z.number().int().min(1).max(100).optional(),
    starting_after: z.string().optional()
  });
  
  /**
   * Reply to email validation schema
   */
  export const ReplyToEmailSchema = z.object({
    reply_to_uuid: z.string()
      .min(1, { message: 'Reply to UUID cannot be empty' })
      .refine(
        (val) => val !== 'test-uuid',
        'reply_to_uuid must be a valid email ID. Use list_emails or get_email tools first to obtain a valid email UUID.'
      ),
    body: z.object({
      html: z.string().optional(),
      text: z.string().optional()
    }).refine(
      (val) => val.html || val.text,
      'Body must contain either html or text content'
    )
  });
  
  /**
   * List emails validation schema
   */
  export const ListEmailsSchema = z.object({
    campaign_id: z.string().optional(),
    account_id: z.string().optional(),
    limit: z.number().int().min(1).max(100).optional(),
    starting_after: z.string().optional()
  });
  
  /**
   * Get email validation schema
   */
  export const GetEmailSchema = z.object({
    email_id: z.string().min(1, { message: 'Email ID cannot be empty' })
  });
  
  /**
   * Validate campaign accounts validation schema
   */
  export const ValidateCampaignAccountsSchema = z.object({
    email_list: z.array(EmailSchema).optional()
  });
  
  /**
   * Get account details validation schema
   */
  export const GetAccountDetailsSchema = z.object({
    email: EmailSchema
  });
  
  // ============================================================================
  // VALIDATION HELPER FUNCTIONS
  // ============================================================================
  
  /**
   * Generic validation function that converts Zod errors to McpError
   */
  export function validateWithSchema<T>(
    schema: z.ZodSchema<T>,
    data: unknown,
    toolName: string
  ): T {
    try {
      return schema.parse(data);
    } catch (error) {
      if (error instanceof z.ZodError) {
        const errorMessages = error.issues.map((err: any) => {
          const path = err.path.length > 0 ? `${err.path.join('.')}: ` : '';
          return `${path}${err.message}`;
        });
        
        throw new McpError(
          ErrorCode.InvalidParams,
          `${toolName} validation failed: ${errorMessages.join('; ')}. Please check your input parameters and try again.`
        );
      }
      
      // Re-throw non-Zod errors
      throw error;
    }
  }
  
  /**
   * Validate campaign creation data with enhanced error messages and contextual guidance
   */
  export function validateCampaignData(args: unknown): z.infer<typeof CreateCampaignSchema> {
    try {
      return validateWithSchema(CreateCampaignSchema, args, 'create_campaign');
    } catch (error: any) {
      // Enhance error messages with contextual guidance
      if (error.message) {
        let enhancedMessage = error.message;
  
        // Add specific guidance for common issues
        if (error.message.includes('email_list') || error.message.includes('Placeholder')) {
          enhancedMessage += '\n\n💡 CRITICAL GUIDANCE: \n1️⃣ Call list_accounts first to see your available sender email addresses\n2️⃣ Only use verified, warmed-up accounts that show status=1 and warmup_status=1\n3️⃣ NEVER use placeholder emails like test@example.com, user@example.com, etc.\n4️⃣ To create ONE campaign with MULTIPLE emails, provide ALL emails in a SINGLE email_list array\n5️⃣ Example: email_list: ["real1@domain.com", "real2@domain.com"] creates ONE campaign with 2 senders';
        }
  
        if (error.message.includes('subject') || error.message.includes('Subject')) {
          enhancedMessage += '\n\n💡 GUIDANCE: Good subject lines are personal and specific. Examples:\n• "{{firstName}}, quick question about {{companyName}}" (48 chars)\n• "Helping {{companyName}} with [specific problem]" (adjust to <50)\n• "{{firstName}}, saw your recent [achievement/news]" (adjust to <50)\n\n⚠️ CRITICAL: Subject line MUST be under 50 characters. If your subject is too long, you MUST shorten it before retrying.';
        }
  
        if (error.message.includes('body') || error.message.includes('Body')) {
          enhancedMessage += '\n\n💡 GUIDANCE: Email body formatting tips:\n• Use \\n for line breaks - they will be automatically converted to <br /> tags for HTML email rendering\n• Double line breaks (\\n\\n) create new paragraphs\n• Personalize with {{firstName}}, {{lastName}}, {{companyName}}\n• Keep it conversational and specific\n• Example: "Hi {{firstName}},\\n\\nI noticed {{companyName}} recently [specific observation].\\n\\nBest regards,\\nYour Name"';
        }
  
        if (error.message.includes('daily_limit')) {
          enhancedMessage += '\n\n💡 GUIDANCE: Daily email limits for cold outreach:\n• Maximum 30 emails per day per account for compliance\n• Higher limits may trigger spam filters\n• Start with lower limits (10-20) for new accounts\n• Gradually increase as account reputation improves';
        }
  
        if (error.message.includes('track_opens') || error.message.includes('track_clicks')) {
          enhancedMessage += '\n\n💡 GUIDANCE: Email tracking considerations:\n• Tracking is disabled by default for better deliverability\n• Many email clients now block tracking pixels\n• Tracking can trigger spam filters and reduce trust\n• Enable only if analytics are absolutely necessary';
        }
  
        if (error.message.includes('name') && error.message.includes('Campaign')) {
          enhancedMessage += '\n\n💡 GUIDANCE: Use descriptive campaign names that help you identify the purpose. Examples:\n• "Q4 Product Launch - Tech Companies"\n• "Holiday Sales Outreach - Existing Customers"\n• "Partnership Inquiry - SaaS Companies"';
        }
  
        error.message = enhancedMessage;
      }
  
      throw error;
    }
  }
  
  /**
   * Validate campaign prerequisite check data with flexible validation
   */
  export function validateCampaignPrerequisiteData(args: unknown): z.infer<typeof CreateCampaignPrerequisiteSchema> {
    return validateWithSchema(CreateCampaignPrerequisiteSchema, args, 'create_campaign_prerequisite');
  }
  
  /**
   * Validate get campaign analytics parameters
   */
  export function validateGetCampaignAnalyticsData(args: unknown): z.infer<typeof GetCampaignAnalyticsSchema> {
    return validateWithSchema(GetCampaignAnalyticsSchema, args, 'get_campaign_analytics');
  }
  
  /**
   * Validate list accounts parameters
   */
  export function validateListAccountsData(args: unknown): z.infer<typeof ListAccountsSchema> {
    return validateWithSchema(ListAccountsSchema, args, 'list_accounts');
  }
  
  /**
   * Validate list campaigns parameters
   */
  export function validateListCampaignsData(args: unknown): z.infer<typeof ListCampaignsSchema> {
    return validateWithSchema(ListCampaignsSchema, args, 'list_campaigns');
  }
  
  /**
   * Validate warmup analytics parameters
   */
  export function validateWarmupAnalyticsData(args: unknown): z.infer<typeof GetWarmupAnalyticsSchema> {
    return validateWithSchema(GetWarmupAnalyticsSchema, args, 'get_warmup_analytics');
  }
  
  /**
   * Validate email verification parameters
   */
  export function validateEmailVerificationData(args: unknown): z.infer<typeof VerifyEmailSchema> {
    return validateWithSchema(VerifyEmailSchema, args, 'verify_email');
  }
  
  /**
   * Validate get campaign parameters
   */
  export function validateGetCampaignData(args: unknown): z.infer<typeof GetCampaignSchema> {
    return validateWithSchema(GetCampaignSchema, args, 'get_campaign');
  }
  
  /**
   * Validate update campaign parameters
   */
  export function validateUpdateCampaignData(args: unknown): z.infer<typeof UpdateCampaignSchema> {
    return validateWithSchema(UpdateCampaignSchema, args, 'update_campaign');
  }
  
  
  
  /**
   * Validate create account parameters
   */
  export function validateCreateAccountData(args: unknown): z.infer<typeof CreateAccountSchema> {
    return validateWithSchema(CreateAccountSchema, args, 'create_account');
  }
  
  /**
   * Validate update account parameters
   */
  export function validateUpdateAccountData(args: unknown): z.infer<typeof UpdateAccountSchema> {
    return validateWithSchema(UpdateAccountSchema, args, 'update_account');

• src/tools/index.ts:25-33 (registration)

  Imports and registers accountTools (including update_account) into the main TOOLS_DEFINITION array used by MCP server.

  import { accountTools } from './account-tools.js';
  import { campaignTools } from './campaign-tools.js';
  import { leadTools } from './lead-tools.js';
  import { emailTools } from './email-tools.js';
  import { analyticsTools } from './analytics-tools.js';
  
  // Category mapping for lazy loading
  const CATEGORY_MAP: Record<string, any[]> = {
    accounts: accountTools,

• src/validation.ts:820-820 (helper)

  Maps the tool name 'update_account' to its validator function in the validation registry.

  'update_account': validateUpdateAccountData,