create_lead
Add new leads to email campaigns by providing essential contact information and custom fields for targeted outreach.
Instructions
Create a new lead
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| companyName | No | Company name | |
| custom_fields | No | Custom fields as key-value pairs | |
| Yes | Lead email address | ||
| firstName | No | First name | |
| lastName | No | Last name | |
| personalization | No | Personalization field | |
| website | No | Company website |
Implementation Reference
- src/handlers/lead-handler.ts:199-250 (handler)Core handler function that executes the create_lead tool logic: builds lead data from args and makes POST request to Instantly.ai /leads endpoint.async function handleCreateLead(args: any, apiKey: string) { console.error('[Instantly MCP] 👤 Executing create_lead...'); // Build lead data with all supported parameters from Instantly.ai API v2 const leadData: any = {}; // Core lead information if (args.campaign) leadData.campaign = args.campaign; if (args.email) leadData.email = args.email; if (args.first_name) leadData.first_name = args.first_name; if (args.last_name) leadData.last_name = args.last_name; if (args.company_name) leadData.company_name = args.company_name; if (args.phone) leadData.phone = args.phone; if (args.website) leadData.website = args.website; if (args.personalization) leadData.personalization = args.personalization; // Advanced parameters if (args.lt_interest_status !== undefined) leadData.lt_interest_status = args.lt_interest_status; if (args.pl_value_lead) leadData.pl_value_lead = args.pl_value_lead; if (args.list_id) leadData.list_id = args.list_id; if (args.assigned_to) leadData.assigned_to = args.assigned_to; // Skip conditions if (args.skip_if_in_workspace !== undefined) leadData.skip_if_in_workspace = args.skip_if_in_workspace; if (args.skip_if_in_campaign !== undefined) leadData.skip_if_in_campaign = args.skip_if_in_campaign; if (args.skip_if_in_list !== undefined) leadData.skip_if_in_list = args.skip_if_in_list; // Verification and blocklist if (args.blocklist_id) leadData.blocklist_id = args.blocklist_id; if (args.verify_leads_for_lead_finder !== undefined) leadData.verify_leads_for_lead_finder = args.verify_leads_for_lead_finder; if (args.verify_leads_on_import !== undefined) leadData.verify_leads_on_import = args.verify_leads_on_import; // Custom variables if (args.custom_variables) leadData.custom_variables = args.custom_variables; console.error(`[Instantly MCP] 📤 Creating lead with data: ${JSON.stringify(leadData, null, 2)}`); const createResult = await makeInstantlyRequest('/leads', { method: 'POST', body: leadData }, apiKey); return { content: [ { type: 'text', text: JSON.stringify({ success: true, lead: createResult, message: 'Lead created successfully' }, null, 2) } ] }; }
- src/tools/lead-tools.ts:47-75 (registration)MCP tool registration/definition including name, description, annotations, and inputSchema for create_lead.{ name: 'create_lead', title: 'Create Lead', description: 'Create lead with custom variables. Use skip_if_in_campaign to prevent duplicates.', annotations: { destructiveHint: false }, inputSchema: { type: 'object', properties: { campaign: { type: 'string', description: 'Campaign UUID' }, email: { type: 'string', description: 'Required' }, first_name: { type: 'string' }, last_name: { type: 'string' }, company_name: { type: 'string' }, phone: { type: 'string' }, website: { type: 'string' }, personalization: { type: 'string' }, lt_interest_status: { type: 'number', description: '-3 to 4' }, pl_value_lead: { type: 'string' }, list_id: { type: 'string' }, assigned_to: { type: 'string' }, skip_if_in_workspace: { type: 'boolean' }, skip_if_in_campaign: { type: 'boolean', description: 'Recommended' }, skip_if_in_list: { type: 'boolean' }, blocklist_id: { type: 'string' }, verify_leads_on_import: { type: 'boolean' }, custom_variables: { type: 'object', description: 'Match campaign field names' } } } },
- src/validation.ts:455-484 (schema)Zod schema for validating create_lead input parameters, matching the tool's inputSchema.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() });
- src/validation.ts:731-733 (schema)Validation wrapper function that applies CreateLeadSchema to input args for create_lead tool.export function validateCreateLeadData(args: unknown): z.infer<typeof CreateLeadSchema> { return validateWithSchema(CreateLeadSchema, args, 'create_lead'); }
- src/handlers/lead-handler.ts:30-31 (registration)Dispatch case in handleLeadTool switch statement that routes create_lead calls to the handler function.case 'create_lead': return handleCreateLead(args, apiKey);