Instantly MCP Server

Instructions

Implementation Reference

• src/handlers/tool-executor.ts:555-615 (handler)

  Handler implementation in executeToolDirectly switch case. Maps tool arguments to Instantly API PATCH payload for /campaigns/{campaign_id} and returns MCP-formatted response.

  case 'update_campaign': {
    if (!args?.campaign_id) {
      throw new McpError(ErrorCode.InvalidParams, 'campaign_id is required');
    }
  
    // Build update data with all provided parameters (excluding campaign_id from body)
    const updateData: any = {};
  
    // Basic campaign settings
    if (args.name !== undefined) updateData.name = args.name;
    if (args.pl_value !== undefined) updateData.pl_value = args.pl_value;
    if (args.is_evergreen !== undefined) updateData.is_evergreen = args.is_evergreen;
  
    // Campaign schedule
    if (args.campaign_schedule !== undefined) updateData.campaign_schedule = args.campaign_schedule;
  
    // Email sequences
    if (args.sequences !== undefined) updateData.sequences = args.sequences;
  
    // Email sending settings
    if (args.email_gap !== undefined) updateData.email_gap = args.email_gap;
    if (args.random_wait_max !== undefined) updateData.random_wait_max = args.random_wait_max;
    if (args.text_only !== undefined) updateData.text_only = args.text_only;
    if (args.email_list !== undefined) updateData.email_list = args.email_list;
    if (args.daily_limit !== undefined) updateData.daily_limit = args.daily_limit;
    if (args.stop_on_reply !== undefined) updateData.stop_on_reply = args.stop_on_reply;
    if (args.email_tag_list !== undefined) updateData.email_tag_list = args.email_tag_list;
  
    // Tracking settings
    if (args.link_tracking !== undefined) updateData.link_tracking = args.link_tracking;
    if (args.open_tracking !== undefined) updateData.open_tracking = args.open_tracking;
  
    // Advanced settings
    if (args.stop_on_auto_reply !== undefined) updateData.stop_on_auto_reply = args.stop_on_auto_reply;
    if (args.daily_max_leads !== undefined) updateData.daily_max_leads = args.daily_max_leads;
    if (args.prioritize_new_leads !== undefined) updateData.prioritize_new_leads = args.prioritize_new_leads;
    if (args.auto_variant_select !== undefined) updateData.auto_variant_select = args.auto_variant_select;
    if (args.match_lead_esp !== undefined) updateData.match_lead_esp = args.match_lead_esp;
    if (args.stop_for_company !== undefined) updateData.stop_for_company = args.stop_for_company;
    if (args.insert_unsubscribe_header !== undefined) updateData.insert_unsubscribe_header = args.insert_unsubscribe_header;
    if (args.allow_risky_contacts !== undefined) updateData.allow_risky_contacts = args.allow_risky_contacts;
    if (args.disable_bounce_protect !== undefined) updateData.disable_bounce_protect = args.disable_bounce_protect;
  
    // CC/BCC lists
    if (args.cc_list !== undefined) updateData.cc_list = args.cc_list;
    if (args.bcc_list !== undefined) updateData.bcc_list = args.bcc_list;
  
    const result = await makeInstantlyRequest(`/campaigns/${args.campaign_id}`, {
      method: 'PATCH',
      body: updateData
    }, apiKey);
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/tools/campaign-tools.ts:72-109 (schema)

  MCP tool definition including name, description, annotations, and inputSchema for update_campaign.

  {
    name: 'update_campaign',
    title: 'Update Campaign',
    description: 'Update campaign settings (partial). Common: name, sequences, tracking, limits, email_list.',
    annotations: { destructiveHint: false },
    inputSchema: {
      type: 'object',
      properties: {
        campaign_id: { type: 'string', description: 'Campaign to update' },
        name: { type: 'string' },
        pl_value: { type: 'number' },
        is_evergreen: { type: 'boolean' },
        campaign_schedule: { type: 'object', properties: { schedules: { type: 'array', items: { type: 'object' } } } },
        sequences: { type: 'array', items: { type: 'object' } },
        email_gap: { type: 'number' },
        random_wait_max: { type: 'number' },
        text_only: { type: 'boolean' },
        email_list: { type: 'array', items: { type: 'string' } },
        daily_limit: { type: 'number' },
        stop_on_reply: { type: 'boolean' },
        email_tag_list: { type: 'array', items: { type: 'string' } },
        link_tracking: { type: 'boolean' },
        open_tracking: { type: 'boolean' },
        stop_on_auto_reply: { type: 'boolean' },
        daily_max_leads: { type: 'number' },
        prioritize_new_leads: { type: 'boolean' },
        auto_variant_select: { type: 'object' },
        match_lead_esp: { type: 'boolean' },
        stop_for_company: { type: 'boolean' },
        insert_unsubscribe_header: { type: 'boolean' },
        allow_risky_contacts: { type: 'boolean' },
        disable_bounce_protect: { type: 'boolean' },
        cc_list: { type: 'array', items: { type: 'string' } },
        bcc_list: { type: 'array', items: { type: 'string' } }
      },
      required: ['campaign_id']
    }
  },

• src/validation.ts:333-405 (schema)

  Zod validation schema UpdateCampaignSchema defining input types and constraints for update_campaign tool parameters.

  export const UpdateCampaignSchema = z.object({
    campaign_id: z.string().min(1, { message: 'Campaign ID cannot be empty' }),
  
    // Basic campaign settings
    name: z.string().min(1).max(255).optional(),
    pl_value: z.number().nullable().optional(),
    is_evergreen: z.boolean().nullable().optional(),
  
    // Campaign schedule
    campaign_schedule: z.object({
      schedules: z.array(z.object({
        name: z.string(),
        timing: z.object({
          from: z.string().regex(/^([01][0-9]|2[0-3]):([0-5][0-9])$/),
          to: z.string().regex(/^([01][0-9]|2[0-3]):([0-5][0-9])$/)
        }),
        days: z.object({
          0: z.boolean().optional(),
          1: z.boolean().optional(),
          2: z.boolean().optional(),
          3: z.boolean().optional(),
          4: z.boolean().optional(),
          5: z.boolean().optional(),
          6: z.boolean().optional()
        }),
        timezone: z.string()
      })).optional(),
      start_date: z.string().datetime().optional(),
      end_date: z.string().datetime().optional()
    }).optional(),
  
    // Email sequences
    sequences: z.array(z.object({
      steps: z.array(z.object({
        type: z.string(),
        delay: z.number(),
        variants: z.array(z.object({
          subject: z.string(),
          body: z.string()
        }))
      }))
    })).optional(),
  
    // Email sending settings
    email_gap: z.number().nullable().optional(),
    random_wait_max: z.number().nullable().optional(),
    text_only: z.boolean().nullable().optional(),
    email_list: z.array(z.string()).optional(),
    daily_limit: z.number().nullable().optional(),
    stop_on_reply: z.boolean().nullable().optional(),
    email_tag_list: z.array(z.string()).optional(),
  
    // Tracking settings
    link_tracking: z.boolean().nullable().optional(),
    open_tracking: z.boolean().nullable().optional(),
  
    // Advanced settings
    stop_on_auto_reply: z.boolean().nullable().optional(),
    daily_max_leads: z.number().nullable().optional(),
    prioritize_new_leads: z.boolean().nullable().optional(),
    auto_variant_select: z.object({
      trigger: z.string()
    }).optional(),
    match_lead_esp: z.boolean().nullable().optional(),
    stop_for_company: z.boolean().nullable().optional(),
    insert_unsubscribe_header: z.boolean().nullable().optional(),
    allow_risky_contacts: z.boolean().nullable().optional(),
    disable_bounce_protect: z.boolean().nullable().optional(),
  
    // CC/BCC lists
    cc_list: z.array(z.string().email()).optional(),
    bcc_list: z.array(z.string().email()).optional()
  });

• src/tools/index.ts:49-55 (registration)

  Aggregates all tool definitions including campaignTools (containing update_campaign) into TOOLS_DEFINITION used by MCP server.

  return [
    ...accountTools,
    ...campaignTools,
    ...leadTools,
    ...emailTools,
    ...analyticsTools,
  ];

• src/validation.ts:708-710 (helper)

  Validation helper function for update_campaign parameters using UpdateCampaignSchema (registered in TOOL_VALIDATORS).

  export function validateUpdateCampaignData(args: unknown): z.infer<typeof UpdateCampaignSchema> {
    return validateWithSchema(UpdateCampaignSchema, args, 'update_campaign');
  }