smartlead_bulk_import_leads

Import multiple leads with contact details into a campaign simultaneously to streamline email marketing list management.

Instructions

Import multiple leads into a campaign at once.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`campaign_id`	Yes	ID of the campaign to add the leads to
`leads`	Yes	Array of leads to import

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);
}
```

Smartlead Simplified MCP Server