list_emails

Instructions

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,
  ];