VerifyForge
VerifyForge

TypeScript SDK

Official TypeScript/JavaScript client library

Package: @verifyforge/sdk

Installation

npm install @verifyforge/sdk

Quick Start

import { VerifyForge } from '@verifyforge/sdk';

const client = new VerifyForge({ apiKey: 'your_api_key_here' });

const result = await client.validate('user@example.com');

if (result.data.isValid) {
  console.log('✓ Email is valid!');
  console.log(`Reachability: ${result.data.reachability}`);
}

Single Email Validation

const result = await client.validate('test@example.com');

console.log(`Valid: ${result.data.isValid}`);
console.log(`Disposable: ${result.data.disposable}`);
console.log(`Role Account: ${result.data.roleAccount}`);
console.log(`Reachability: ${result.data.reachability}`);

// Check MX records
for (const mx of result.data.mxRecordsList) {
  console.log(`MX: ${mx.exchange} (priority: ${mx.priority})`);
}

Bulk Email Validation

Validate up to 100 emails in a single request:

const emails = [
  'user1@example.com',
  'user2@example.com',
  'user3@example.com',
];

const result = await client.validateBulk(emails);

console.log(`Total: ${result.data.summary.total}`);
console.log(`Duplicates removed: ${result.data.summary.duplicatesRemoved}`);
console.log(`Credits used: ${result.creditsUsed}`);

for (const item of result.data.results) {
  console.log(`${item.email}: ${item.isValid ? '✓' : '✗'}`);
}

Error Handling

import {
  VerifyForge,
  AuthenticationError,
  InsufficientCreditsError,
  ValidationError,
} from '@verifyforge/sdk';

try {
  const result = await client.validate('test@example.com');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof InsufficientCreditsError) {
    console.error('Not enough credits');
  } else if (error instanceof ValidationError) {
    console.error(`Validation error: ${error.message}`);
  }
}

Configuration

const client = new VerifyForge({
  apiKey: 'your_api_key',
  baseUrl: 'https://verifyforge.com', // Optional
  timeout: 30000, // Optional, in milliseconds
});

TypeScript Types

import {
  ValidationResponse,
  BulkValidationResponse,
  ValidationResult,
} from '@verifyforge/sdk';

const result: ValidationResponse = await client.validate('test@example.com');
const validation: ValidationResult = result.data;

Browser Usage

<script type="module">
  import { VerifyForge } from 'https://unpkg.com/@verifyforge/sdk';

  const client = new VerifyForge({ apiKey: 'your_api_key' });
  const result = await client.validate('test@example.com');
  console.log(result);
</script>

API Reference

Constructor

new VerifyForge(config: VerifyForgeConfig)

Parameters:

  • config.apiKey (string, required): Your API key
  • config.baseUrl (string, optional): Base URL, defaults to "https://verifyforge.com"
  • config.timeout (number, optional): Timeout in milliseconds, defaults to 30000

Methods

validate(email: string): Promise<ValidationResponse>

Validate a single email address.

Throws:

  • ValidationError: Invalid email format
  • InsufficientCreditsError: Insufficient credits
  • APIError: Validation failed

validateBulk(emails: string[]): Promise<BulkValidationResponse>

Validate up to 100 email addresses.

Throws:

  • ValidationError: Invalid email list or exceeds 100 emails
  • InsufficientCreditsError: Insufficient credits
  • APIError: Validation failed

Error Classes

All errors extend VerifyForgeError:

  • AuthenticationError: Invalid API key (401)
  • InsufficientCreditsError: Insufficient credits (402)
  • ValidationError: Request validation failed (400)
  • RateLimitError: Rate limit exceeded (429)
  • APIError: General API error (5xx)
  • NetworkError: Network request failed

Requirements

  • Node.js 16.0.0 or higher
  • Modern browser with fetch support

Links