verifyhawk

Official Node.js/TypeScript SDK for VerifyHawk — AI-powered email verification API.

Install

npm install verifyhawk

Quick Start

import VerifyHawk from 'verifyhawk';

const vh = new VerifyHawk('vh_live_your_api_key');

const result = await vh.verify('[email protected]');

if (result.isValid) {
  console.log('Email is valid', result.score);
} else {
  console.log('Flags:', result.explanation.redFlags);
}

Bulk Verify

Verify up to 100 emails in a single request:

const { results, summary } = await vh.verifyBulk([
  '[email protected]',
  '[email protected]',
]);

console.log(`${summary.valid} valid, ${summary.risky} risky, ${summary.invalid} invalid`);

OTP Flow

Send a one-time code, then verify it:

// Send — invalid/disposable emails are rejected before sending
const sendResult = await vh.otp.send('[email protected]', {
  appName: 'MyApp',
  codeType: 'numeric',
  expiresIn: 300, // 5 minutes
});

if (sendResult.sent) {
  // User enters the code they received
  const verifyResult = await vh.otp.verify('[email protected]', '123456');
  console.log(verifyResult.verified); // true or false
}

Check if a pending code exists:

const status = await vh.otp.status('[email protected]');
if (status.pending) {
  console.log('Code expires at', status.expiresAt);
}

TypeScript

Fully typed — no @types package needed. All request options and responses have complete TypeScript interfaces.

import VerifyHawk, { VerifyResult, VerifyHawkError } from 'verifyhawk';

Error Handling

import VerifyHawk, { VerifyHawkError } from 'verifyhawk';

const vh = new VerifyHawk('your-api-key');

try {
  const result = await vh.verify('[email protected]');
} catch (err) {
  if (err instanceof VerifyHawkError) {
    console.error(`API error ${err.statusCode}: ${err.message}`);
  }
}

Local Development

Point the SDK at your local dev server:

const vh = new VerifyHawk({
  apiKey: 'vh_live_your_api_key',
  baseUrl: 'http://localhost:3000',
});

Docs

Full documentation at verifyhawk.pro/docs.

License

MIT