list_accounts

Instructions

Implementation Reference

• src/handlers/tool-executor.ts:118-151 (handler)

  Main handler execution logic for 'list_accounts' tool: validates parameters, calls getAllAccounts service, handles pagination, and returns formatted MCP response.

  case 'list_accounts': {
    console.error('[Instantly MCP] 📊 Executing list_accounts (sequential pagination)...');
  
    try {
      // Build pagination and filter parameters
      const paginationParams = {
        limit: args?.limit || 100,
        ...(args?.starting_after && { starting_after: args.starting_after }),
        ...(args?.search && { search: args.search }),
        ...(args?.status !== undefined && { status: args.status }),
        ...(args?.provider_code !== undefined && { provider_code: args.provider_code }),
        ...(args?.tag_ids && { tag_ids: args.tag_ids })
      };
  
      // Validate parameters
      const validatedData = validateListAccountsData(paginationParams);
      console.error('[Instantly MCP] 📊 Parameters validated:', validatedData);
  
      // Fetch ONE page of accounts
      const result = await getAllAccounts(apiKey, paginationParams);
  
      // Return single page with clear pagination metadata
      // Using TOON format for token efficiency (30-60% reduction for tabular data)
      return createMCPResponse({
        data: result.data,
        pagination: result.pagination,
        metadata: result.metadata,
        success: true
      });
    } catch (error: any) {
      console.error('[Instantly MCP] ❌ Error in list_accounts:', error.message);
      throw error;
    }
  }

• src/validation.ts:276-280 (schema)

  Zod runtime validation schema for list_accounts input parameters.

  export const ListAccountsSchema = z.object({
    limit: PaginationLimitSchema, // Already optional in the schema definition
    starting_after: z.string().optional(),
    get_all: z.boolean().optional()
  });

• src/tools/account-tools.ts:10-26 (registration)

  Tool registration/definition including metadata, description, and inputSchema for MCP protocol.

  {
    name: 'list_accounts',
    title: 'List Accounts',
    description: 'List email accounts with pagination. Filter by status, provider, or tags.',
    annotations: { readOnlyHint: true },
    inputSchema: {
      type: 'object',
      properties: {
        limit: { type: 'number', description: '1-100, default: 100' },
        starting_after: { type: 'string', description: 'Cursor from pagination.next_starting_after' },
        search: { type: 'string', description: 'Search by email domain' },
        status: { type: 'number', description: '1=Active, 2=Paused, -1/-2/-3=Errors', enum: [1, 2, -1, -2, -3] },
        provider_code: { type: 'number', description: '1=IMAP, 2=Google, 3=Microsoft, 4=AWS', enum: [1, 2, 3, 4] },
        tag_ids: { type: 'string', description: 'Comma-separated tag IDs' }
      }
    }
  },

• src/services/account-service.ts:19-98 (helper)

  Core service function getAllAccounts that performs the actual API call to Instantly.ai /accounts endpoint, handles pagination and filtering, and returns structured data used by the handler.

  export async function getAllAccounts(apiKey?: string, params?: any): Promise<any> {
    console.error('[Instantly MCP] 📊 Retrieving accounts (sequential pagination)...');
  
    try {
      const startTime = Date.now();
  
      // Build query parameters for single page request
      const queryParams: any = {
        limit: params?.limit || 100, // Default to 100 items per page (API maximum)
      };
  
      // Add cursor if provided (for subsequent pages)
      if (params?.starting_after) {
        queryParams.starting_after = params.starting_after;
        console.error(`[Instantly MCP] 📄 Fetching page with cursor: ${params.starting_after}`);
      } else {
        console.error('[Instantly MCP] 📄 Fetching first page');
      }
  
      // Add API filter parameters (sent to Instantly API)
      if (params?.search) {
        queryParams.search = params.search;
        console.error(`[Instantly MCP] 🔍 Filtering by search: ${params.search}`);
      }
      if (params?.status !== undefined) {
        queryParams.status = params.status;
        console.error(`[Instantly MCP] 🔍 Filtering by status: ${params.status}`);
      }
      if (params?.provider_code !== undefined) {
        queryParams.provider_code = params.provider_code;
        console.error(`[Instantly MCP] 🔍 Filtering by provider_code: ${params.provider_code}`);
      }
      if (params?.tag_ids) {
        queryParams.tag_ids = params.tag_ids;
        console.error(`[Instantly MCP] 🔍 Filtering by tag_ids: ${params.tag_ids}`);
      }
  
      // Make single API call to /accounts endpoint
      const response = await makeInstantlyRequest(ENDPOINTS.ACCOUNTS, {
        method: 'GET',
        params: queryParams
      }, apiKey);
  
      const elapsed = Date.now() - startTime;
  
      // Extract data and pagination info from response
      const data = Array.isArray(response) ? response : (response.items || response.data || []);
      const nextCursor = response.next_starting_after || null;
      const hasMore = !!nextCursor;
  
      console.error(`[Instantly MCP] ✅ Retrieved ${data.length} accounts in ${elapsed}ms (has_more: ${hasMore})`);
  
      // Return single page with clear pagination metadata
      return {
        data,
        pagination: {
          returned_count: data.length,
          has_more: hasMore,
          next_starting_after: nextCursor,
          limit: queryParams.limit,
          current_page_note: hasMore
            ? `Retrieved ${data.length} accounts. More results available. To get next page, call list_accounts again with starting_after='${nextCursor}'`
            : `Retrieved all available accounts (${data.length} items).`
        },
        metadata: {
          request_time_ms: elapsed,
          success: true,
          filters_applied: {
            ...(params?.search && { search: params.search }),
            ...(params?.status !== undefined && { status: params.status }),
            ...(params?.provider_code !== undefined && { provider_code: params.provider_code }),
            ...(params?.tag_ids && { tag_ids: params.tag_ids })
          }
        }
      };
    } catch (error) {
      console.error('[Instantly MCP] ❌ Error retrieving accounts:', error);
      throw error;
    }
  }

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

  Central tools registry where accountTools (including list_accounts) is imported and included in TOOLS_DEFINITION array used by MCP server for tool listing and registration.

  export const TOOLS_DEFINITION = buildToolsDefinition();