JavaScript & Node.js SDK

Official JavaScript SDK for the Truelist email validation API. Works in Node.js 18+, Vercel Edge Functions, Cloudflare Workers, and Deno.

Installation

npm install truelist

Quick start

import Truelist from "truelist";

const truelist = new Truelist("your-api-key");
const result = await truelist.email.validate("user@example.com");
console.log(result.state); // "ok"

Validate an email

import { isValid, isDisposable, isRole } from "truelist";

const result = await truelist.email.validate("user@example.com");

console.log(result.email);      // "user@example.com"
console.log(result.domain);     // "example.com"
console.log(result.state);      // "ok" | "email_invalid" | "risky" | "unknown" | "accept_all"
console.log(result.subState);   // "email_ok" | "is_disposable" | ...
console.log(result.suggestion); // null or suggested correction
console.log(result.verifiedAt); // "2026-02-21T10:00:00.000Z"

// Convenience methods
console.log(isValid(result));      // true
console.log(isDisposable(result)); // false
console.log(isRole(result));       // false

Configuration

const truelist = new Truelist("your-api-key", {
  baseUrl: "https://api.truelist.io",
  timeout: 30000,
  maxRetries: 2,
});

Cancel a request

Pass an AbortSignal to cancel in-flight requests:

const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

const result = await truelist.email.validate("user@example.com", {
  signal: controller.signal,
});

Error handling

import Truelist, {
  AuthenticationError,
  RateLimitError,
  ApiError,
  TruelistError
} from "truelist";

try {
  const result = await truelist.email.validate("user@example.com");
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Bad API key");
  } else if (error instanceof RateLimitError) {
    console.error("Rate limited, retry after:", error.retryAfter);
  } else if (error instanceof ApiError) {
    console.error("API error:", error.status, error.body);
  }
}

Retries and rate limiting

• Retried status codes: 429, 500, 502, 503, 504
• Retried errors: Network failures, timeouts
• Backoff: 500ms, 1000ms, 2000ms (with jitter)
• Retry-After: Respected on 429 responses

Set maxRetries: 0 to disable.

Account info

const account = await truelist.account.get();
console.log(account.email);               // "you@company.com"
console.log(account.account.paymentPlan); // "pro"

TypeScript types

All types are exported:

import type {
  ValidationResult,
  ValidationState,
  ValidationSubState,
  AccountInfo,
  TruelistOptions,
  ValidateOptions,
} from "truelist";

Framework integrations

React

npm install @truelist/react

Provides a TruelistProvider, useEmailValidation hook, and EmailInput component with built-in debouncing.

import { TruelistProvider, useEmailValidation } from "@truelist/react";

function App() {
  return (
    <TruelistProvider apiKey="your-api-key">
      <SignupForm />
    </TruelistProvider>
  );
}

function SignupForm() {
  const { validate, result, isValidating } = useEmailValidation();
  return (
    <input
      type="email"
      onChange={(e) => validate(e.target.value)}
      aria-invalid={result?.state === "email_invalid"}
    />
  );
}

Includes Zod integration (@truelist/react/zod) and React Hook Form integration (@truelist/react/react-hook-form).

Next.js

npm install @truelist/nextjs

Server Actions, Route Handlers, and Zod integration. Reads TRUELIST_API_KEY from environment automatically.

"use server";
import { validateEmail } from "@truelist/nextjs/server";

export async function checkEmail(formData: FormData) {
  const result = await validateEmail(formData.get("email") as string);
  if (!result.isValid) {
    return { error: "Invalid email", suggestion: result.suggestion };
  }
  return { success: true };
}

Also provides createValidationHandler for Route Handlers and truelistEmail() for Zod schemas.

Vue

npm install @truelist/vue

Vue composables and components with reactive v-model binding.

<script setup>
import { useEmailValidation } from '@truelist/vue'
const { email, result, isValidating } = useEmailValidation({
  apiKey: 'your-api-key'
})
</script>

<template>
  <input v-model="email" type="email" />
  <span v-if="result?.state === 'ok'">Valid!</span>
</template>

Svelte

npm install @truelist/svelte

Svelte actions, stores, and components using Svelte 5 runes.

<script>
  import { truelist } from '@truelist/svelte';
  let result = $state(null);
</script>

<input
  type="email"
  use:truelist={{
    apiKey: 'your-api-key',
    debounceMs: 500,
    validateOn: 'blur',
    onResult: (r) => result = r
  }}
/>

Package links