findmailx/README.md

FindMailX API client

# FindMailX API Client

Official Node.js client for the FindMailX API - Find and verify email addresses with confidence.

## Installation

```bash
npm install findmailx
```

## Usage

```typescript
import { FindMailXClient } from "findmailx";

const client = new FindMailXClient({
  apiKey: "your_api_key",
});

// Find an email address
const finder = await client.findEmail({
  domain: "company.com",
  firstName: "John",
  lastName: "Doe",
});

// Verify an email address
const verifier = await client.verifyEmail("john.doe@company.com");
```

## Configuration

```typescript
const client = new FindMailXClient({
  apiKey: "your_api_key",
  baseUrl: "https://www.findmailx.com/api/v1", // optional
});
```

## Sample Requests

### Find Email by Full Name

```typescript
const result = await client.findEmail({
  domain: "microsoft.com",
  fullName: "Satya Nadella",
});

// Sample Response
{
  status: "success",
  result: {
    status: "found",
    email: "satya@microsoft.com",
    name: "Satya Nadella",
    domain: "microsoft.com",
    verification: {
      status: "safe",
      score: 96,
      disposable: false,
      webmail: false
    }
  }
}
```

### Find Email by First and Last Name

```typescript
const result = await client.findEmail({
  domain: "microsoft.com",
  firstName: "Satya",
  lastName: "Nadella",
});

// Sample Response
{
  status: "success",
  result: {
    status: "found",
    email: "satya.nadella@microsoft.com",
    name: "Satya Nadella",
    domain: "microsoft.com",
    verification: {
      status: "safe",
      score: 96,
      disposable: false,
      webmail: false
    }
  }
}
```

### Verify Email

```typescript
const result = await client.verifyEmail("satya@microsoft.com");

// Sample Response
{
  status: "success",
  result: {
    status: "safe",
    email: "satya@microsoft.com",
    score: 96,
    disposable: false,
    webmail: false
  }
}
```

### Error Response Examples

```typescript
// Rate Limit Error
{
  name: "RateLimitError",
  message: "Rate limit exceeded"
}

// No Credits Error
{
  name: "NoCreditsError",
  message: "You are out of credits"
}

// Authentication Error
{
  name: "AuthenticationError",
  message: "Invalid API key"
}
```

## Email Finder

```typescript
const result = await client.findEmail({
  domain: "company.com",
  // Use either fullName OR firstName + lastName
  fullName: "John Doe",
  // OR
  firstName: "John",
  lastName: "Doe",
});

interface FinderResult {
  status: "found" | "not_found";
  email?: string;
  name?: string;
  domain?: string;
  verification?: VerificationResult;
}
```

## Email Verification

```typescript
const result = await client.verifyEmail("john.doe@company.com");

interface VerificationResult {
  status: "safe" | "risky" | "invalid";
  email?: string;
  score: number;
  disposable: boolean;
  webmail: boolean;
}
```

## Error Handling

```typescript
import {
  FindMailXError,
  AuthenticationError,
  RateLimitError,
  NoCreditsError,
} from "findmailx";

try {
  await client.verifyEmail("test@example.com");
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Handle invalid API key
  } else if (error instanceof RateLimitError) {
    // Handle rate limit (10 requests/second)
  } else if (error instanceof NoCreditsError) {
    // Handle insufficient credits
  }
}
```

## License

MIT