neverbounce_validate_email

Instructions

Implementation Reference

• src/index.ts:212-261 (handler)

  Handler logic for the neverbounce_validate_email tool: validates params, makes API call to NeverBounce with retry, interprets result, and returns formatted response or error.

  case 'neverbounce_validate_email': {
    if (!isValidateEmailParams(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid arguments for neverbounce_validate_email. You must provide an email address.'
      );
    }
  
    try {
      // URL encode the email address
      const encodedEmail = encodeURIComponent(args.email);
      
      const response = await withRetry(
        async () => apiClient.get(`/single/check?key=${NEVERBOUNCE_API_KEY}&email=${encodedEmail}&timeout=${args.timeout || 30000}`),
        'validate email'
      );
      
      const data = response.data;
      
      // Format the response for better readability
      const formattedResponse = {
        email: args.email,
        status: data.status,
        result: interpretVerificationResult(data.result),
        result_code: data.result,
        flags: data.flags || [],
        suggested_correction: data.suggested_correction || null,
        execution_time: data.execution_time
      };
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(formattedResponse, null, 2),
          },
        ],
        isError: false,
      };
    } catch (error) {
      const errorMessage = axios.isAxiosError(error)
        ? `API Error: ${error.response?.data?.message || error.message}`
        : `Error: ${error instanceof Error ? error.message : String(error)}`;
  
      return {
        content: [{ type: 'text', text: errorMessage }],
        isError: true,
      };
    }
  }

• src/index.ts:18-35 (schema)

  Tool definition including name, description, and input schema for neverbounce_validate_email.

  const VALIDATE_EMAIL_TOOL: Tool = {
    name: 'neverbounce_validate_email',
    description: 'Validate an email address to check if it\'s valid and deliverable.',
    inputSchema: {
      type: 'object',
      properties: {
        email: {
          type: 'string',
          description: 'The email address to validate',
        },
        timeout: {
          type: 'number',
          description: 'Timeout in milliseconds (optional, default: 30000)',
        }
      },
      required: ['email'],
    },
  };

• src/index.ts:190-194 (registration)

  Registration of the tool in the ListToolsRequestSchema handler.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      VALIDATE_EMAIL_TOOL,
    ],
  }));

• src/index.ts:44-64 (helper)

  Type guard function to validate input parameters for the tool.

  function isValidateEmailParams(args: unknown): args is ValidateEmailParams {
    if (
      typeof args !== 'object' ||
      args === null ||
      !('email' in args) ||
      typeof (args as { email: unknown }).email !== 'string'
    ) {
      return false;
    }
  
    // Optional parameters
    if (
      'timeout' in args &&
      (args as { timeout: unknown }).timeout !== undefined &&
      typeof (args as { timeout: unknown }).timeout !== 'number'
    ) {
      return false;
    }
  
    return true;
  }

• src/index.ts:172-187 (helper)

  Helper function to interpret NeverBounce verification result codes into human-readable strings.

  function interpretVerificationResult(result: number): string {
    switch (result) {
      case 0:
        return 'Valid';
      case 1:
        return 'Invalid';
      case 2:
        return 'Disposable';
      case 3:
        return 'Catchall';
      case 4:
        return 'Unknown';
      default:
        return 'Unknown';
    }
  }