list_accounts
Retrieve all valid sending email accounts from your workspace to use as sender addresses when creating email campaigns, ensuring campaign creation success.
Instructions
List all sending accounts in the workspace. PREREQUISITE FOR CAMPAIGN CREATION: You MUST call this tool first before creating any campaigns to obtain valid email addresses for the email_list parameter. The returned accounts are the only valid sending addresses that can be used in campaigns.
CRITICAL FOR SUCCESS: Campaign creation will fail if you use email addresses that are not returned by this endpoint. Always use the exact email addresses from this response.
COMPLETE PAGINATION: To get ALL accounts, use one of these approaches:
Set limit=100 or higher (automatically triggers complete pagination)
Set get_all=true (forces complete pagination)
Use limit="all" (string triggers complete pagination)
PAGINATION ALGORITHM: When requesting all accounts, the tool will automatically:
Start with limit=100 per page
Continue fetching until next_starting_after is null or empty results
Report progress: "Retrieved 100... 200... 304 total accounts"
Return complete dataset with validation
ACCOUNT STATUS: Look for accounts with status=1, setup_pending=false, warmup_status=1 for campaign eligibility.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| get_all | No | Set to true to force complete pagination and retrieve ALL accounts regardless of limit setting. | |
| limit | No | Number of accounts to return (1-100, default: 20). Use limit=100+ or limit="all" to trigger complete pagination that retrieves ALL accounts automatically. | |
| starting_after | No | ID of the last item from previous page for manual pagination. Not needed when using complete pagination (limit=100+). |
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' } } } },
- 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();