list_emails
Retrieve filtered email lists from campaigns or accounts with pagination controls to manage and analyze email data efficiently.
Instructions
List emails with filters and pagination
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| account_id | No | Filter by account | |
| campaign_id | No | Filter by campaign | |
| limit | No | Number of emails to return (1-100, default: 20) | |
| starting_after | No | ID of the last item from previous page for pagination |
Implementation Reference
- src/handlers/tool-executor.ts:905-950 (handler)Handler function for list_emails tool. Builds query parameters from input args, calls Instantly API endpoint '/emails', adds pagination metadata, and formats response.case 'list_emails': { console.error('[Instantly MCP] 📧 Executing list_emails...'); const emailsParams: any = {}; // Pagination parameters emailsParams.limit = args.limit || 100; // Default to 100 items per page (API maximum) if (args.starting_after) emailsParams.starting_after = args.starting_after; // Filtering parameters if (args.campaign_id) emailsParams.campaign_id = args.campaign_id; if (args.search) emailsParams.search = args.search; if (args.i_status !== undefined) emailsParams.i_status = args.i_status; if (args.eaccount) emailsParams.eaccount = args.eaccount; if (args.is_unread !== undefined) emailsParams.is_unread = args.is_unread; if (args.has_reminder !== undefined) emailsParams.has_reminder = args.has_reminder; if (args.mode) emailsParams.mode = args.mode; if (args.preview_only !== undefined) emailsParams.preview_only = args.preview_only; if (args.sort_order) emailsParams.sort_order = args.sort_order; if (args.scheduled_only !== undefined) emailsParams.scheduled_only = args.scheduled_only; if (args.assigned_to) emailsParams.assigned_to = args.assigned_to; if (args.lead) emailsParams.lead = args.lead; if (args.company_domain) emailsParams.company_domain = args.company_domain; if (args.marked_as_done !== undefined) emailsParams.marked_as_done = args.marked_as_done; if (args.email_type) emailsParams.email_type = args.email_type; const emailsResult = await makeInstantlyRequest('/emails', { params: emailsParams }, apiKey); // Add metadata about pagination const metadata: any = { request_time_ms: Date.now(), note: `Retrieved ${emailsResult.items?.length || 0} emails.` }; if (emailsResult.next_starting_after) { metadata.note += ` More results available. To retrieve additional pages, call this tool again with starting_after parameter set to: ${emailsResult.next_starting_after}`; } else { metadata.note += ' All results retrieved (no more pages available).'; } return createMCPResponse({ ...emailsResult, metadata, success: true }); }
- src/tools/email-tools.ts:11-37 (schema)Tool definition including input schema for list_emails, used for MCP registration and client-side validation.name: 'list_emails', title: 'List Emails', description: 'List emails with pagination. Filter by campaign, account, type, or status.', annotations: { readOnlyHint: true }, inputSchema: { type: 'object', properties: { limit: { type: 'number', description: '1-100, default: 100' }, starting_after: { type: 'string', description: 'Cursor from pagination' }, search: { type: 'string', description: 'Search (use "thread:UUID" for threads)' }, campaign_id: { type: 'string' }, i_status: { type: 'number', description: 'Interest status' }, eaccount: { type: 'string', description: 'Sender accounts (comma-separated)' }, is_unread: { type: 'boolean' }, has_reminder: { type: 'boolean' }, mode: { type: 'string', enum: ['emode_focused', 'emode_others', 'emode_all'] }, preview_only: { type: 'boolean' }, sort_order: { type: 'string', enum: ['asc', 'desc'] }, scheduled_only: { type: 'boolean' }, assigned_to: { type: 'string' }, lead: { type: 'string', description: 'Lead email' }, company_domain: { type: 'string' }, marked_as_done: { type: 'boolean' }, email_type: { type: 'string', enum: ['received', 'sent', 'manual'] } } } },
- src/validation.ts:553-558 (schema)Zod validation schema for list_emails input parameters.export const ListEmailsSchema = z.object({ campaign_id: z.string().optional(), account_id: z.string().optional(), limit: z.number().int().min(1).max(100).optional(), starting_after: z.string().optional() });
- src/validation.ts:773-774 (helper)Validation helper function for list_emails parameters using Zod schema.export function validateListEmailsData(args: unknown): z.infer<typeof ListEmailsSchema> { return validateWithSchema(ListEmailsSchema, args, 'list_emails');
- src/tools/index.ts:49-55 (registration)Aggregation of all tool definitions including emailTools (containing list_emails) into TOOLS_DEFINITION array used by MCP server.return [ ...accountTools, ...campaignTools, ...leadTools, ...emailTools, ...analyticsTools, ];