Email Validation

Instructions

Implementation Reference

• src/api/leadfuze-client.ts:91-96 (handler)

  Core handler function in LeadFuzeClient that makes the API request to validate the email address.

  async validateEmail(params: EmailValidationParams): Promise<ValidationResponse> {
    return this.request<ValidationResponse>("/verification/email", {
      email: params.email,
      cache_ttl: params.cache_ttl ?? 600,
    });
  }

• src/index.ts:175-222 (registration)

  MCP tool registration for 'validate_email', including input schema and wrapper handler that calls the client.

  server.registerTool(
    "validate_email",
    {
      title: "Email Validation",
      description:
        "Validate an email address to check if it's deliverable, has valid format, and assess its risk level. Returns detailed validation results including deliverability, catch-all status, and mail server information.",
      inputSchema: {
        email: z.string().email().describe("The email address to validate"),
      },
      annotations: {
        title: "Email Validation",
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: true,
      },
    },
    async ({ email }) => {
      try {
        const client = getClient();
        const response = await client.validateEmail({ email });
  
        const formattedResponse = formatValidationResponse(response);
  
        return {
          content: [
            {
              type: "text" as const,
              text: formattedResponse,
            },
          ],
        };
      } catch (error) {
        const errorMessage =
          error instanceof Error ? error.message : "An unknown error occurred";
  
        return {
          content: [
            {
              type: "text" as const,
              text: `Error validating email: ${errorMessage}`,
            },
          ],
          isError: true,
        };
      }
    }
  );

• src/index.ts:181-183 (schema)

  Zod input schema for the validate_email tool.

  inputSchema: {
    email: z.string().email().describe("The email address to validate"),
  },

• src/types/enrichment.ts:155-158 (schema)

  TypeScript interface for email validation parameters.

  export interface EmailValidationParams {
    email: string;
    cache_ttl?: number;
  }

• src/api/leadfuze-client.ts:231-268 (helper)

  Helper function to format the validation response into human-readable text for the MCP tool output.

  export function formatValidationResponse(response: ValidationResponse): string {
    if (!response.success) {
      return "Error: The validation request was not successful.";
    }
  
    const data = response.data;
    const result = data.result;
    const lines: string[] = [];
  
    // Status summary with emoji
    const statusEmoji = data.status === "valid" ? "✅" : data.status === "invalid" ? "❌" : "⚠️";
    lines.push(`${statusEmoji} Email: ${data.email}`);
    lines.push(`Status: ${data.status.toUpperCase()}`);
    lines.push(`Risk Level: ${data.risk_level}`);
  
    lines.push("");
    lines.push("Validation Details:");
    lines.push(`- Valid Format: ${result.valid_format ? "Yes" : "No"}`);
    lines.push(`- Deliverable: ${result.deliverable ? "Yes" : "No"}`);
    lines.push(`- Host Exists: ${result.host_exists ? "Yes" : "No"}`);
    lines.push(`- Catch-All: ${result.catch_all ? "Yes" : "No"}`);
    lines.push(`- Full Inbox: ${result.full_inbox ? "Yes" : "No"}`);
  
    lines.push("");
    lines.push("Email Info:");
    lines.push(`- Username: ${data.username}`);
    lines.push(`- Domain: ${data.domain}`);
  
    lines.push("");
    lines.push(`Credits Used: ${response.credits.used} | Remaining: ${response.credits.remaining}`);
  
    // Add raw data for completeness
    lines.push("");
    lines.push("--- Raw Data ---");
    lines.push(JSON.stringify(response.data, null, 2));
  
    return lines.join("\n");
  }