smartlead_bulk_import_leads

Instructions

Implementation Reference

• src/handlers/lead.ts:266-304 (handler)

  Core handler function that validates input and performs bulk import of leads via POST to `/campaigns/{campaign_id}/leads/bulk` API endpoint.

  async function handleBulkImportLeads(
    args: unknown,
    apiClient: AxiosInstance,
    withRetry: <T>(operation: () => Promise<T>, context: string) => Promise<T>
  ) {
    if (!isBulkImportLeadsParams(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid arguments for smartlead_bulk_import_leads'
      );
    }
  
    try {
      const response = await withRetry(
        async () => apiClient.post(`/campaigns/${args.campaign_id}/leads/bulk`, {
          leads: args.leads
        }),
        'bulk import leads'
      );
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(response.data, null, 2),
          },
        ],
        isError: false,
      };
    } catch (error: any) {
      return {
        content: [{ 
          type: 'text', 
          text: `API Error: ${error.response?.data?.message || error.message}` 
        }],
        isError: true,
      };
    }
  }

• src/tools/lead.ts:167-219 (schema)

  Tool definition with name, description, category, and input schema specifying campaign_id and array of lead objects (each requiring email).

  export const BULK_IMPORT_LEADS_TOOL: CategoryTool = {
    name: 'smartlead_bulk_import_leads',
    description: 'Import multiple leads into a campaign at once.',
    category: ToolCategory.LEAD_MANAGEMENT,
    inputSchema: {
      type: 'object',
      properties: {
        campaign_id: {
          type: 'number',
          description: 'ID of the campaign to add the leads to',
        },
        leads: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              email: {
                type: 'string',
                description: 'Email address of the lead',
              },
              first_name: {
                type: 'string',
                description: 'First name of the lead',
              },
              last_name: {
                type: 'string',
                description: 'Last name of the lead',
              },
              company: {
                type: 'string',
                description: 'Company of the lead',
              },
              title: {
                type: 'string',
                description: 'Job title of the lead',
              },
              phone: {
                type: 'string',
                description: 'Phone number of the lead',
              },
              custom_fields: {
                type: 'object',
                description: 'Custom fields for the lead',
              },
            },
            required: ['email'],
          },
          description: 'Array of leads to import',
        },
      },
      required: ['campaign_id', 'leads'],
    },
  };

• src/types/lead.ts:216-266 (schema)

  Runtime type guard for validating BulkImportLeadsParams, checking campaign_id, leads array, and each lead's required email plus optional fields.

  export function isBulkImportLeadsParams(args: unknown): args is BulkImportLeadsParams {
    if (
      typeof args !== 'object' ||
      args === null ||
      !('campaign_id' in args) ||
      !('leads' in args) ||
      typeof (args as { campaign_id: unknown }).campaign_id !== 'number' ||
      !Array.isArray((args as { leads: unknown }).leads)
    ) {
      return false;
    }
    
    const params = args as BulkImportLeadsParams;
    
    // Validate each lead in the leads array
    for (const lead of params.leads) {
      if (
        typeof lead !== 'object' ||
        lead === null ||
        !('email' in lead) ||
        typeof lead.email !== 'string'
      ) {
        return false;
      }
      
      // Optional fields validation
      if (lead.first_name !== undefined && typeof lead.first_name !== 'string') {
        return false;
      }
      if (lead.last_name !== undefined && typeof lead.last_name !== 'string') {
        return false;
      }
      if (lead.company !== undefined && typeof lead.company !== 'string') {
        return false;
      }
      if (lead.title !== undefined && typeof lead.title !== 'string') {
        return false;
      }
      if (lead.phone !== undefined && typeof lead.phone !== 'string') {
        return false;
      }
      if (
        lead.custom_fields !== undefined && 
        (typeof lead.custom_fields !== 'object' || lead.custom_fields === null)
      ) {
        return false;
      }
    }
    
    return true;
  }

• src/index.ts:207-209 (registration)

  Registers the leadTools array (containing smartlead_bulk_import_leads) into the MCP toolRegistry if leadManagement category is enabled by license.

  if (enabledCategories.leadManagement) {
    toolRegistry.registerMany(leadTools);
  }

• src/handlers/lead.ts:36-38 (handler)

  Switch case in handleLeadTool that dispatches smartlead_bulk_import_leads calls to the specific handleBulkImportLeads implementation.

  case 'smartlead_bulk_import_leads': {
    return handleBulkImportLeads(args, apiClient, withRetry);
  }