truelist

Official Node.js SDK for the Truelist.io email validation API.

npm install truelist

Start free — 100 validations + 10 enhanced credits, no credit card required. Get your API key →

Quick Start

import Truelist from "truelist";

const truelist = new Truelist("your-api-key");
const result = await truelist.email.validate("[email protected]");
console.log(result.state); // "ok"

Usage

Validate an Email

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

const result = await truelist.email.validate("[email protected]");

console.log(result.email);      // "[email protected]"
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

Check Account Info

const account = await truelist.account.get();
console.log(account.email);               // "[email protected]"
console.log(account.name);                // "Your Name"
console.log(account.uuid);                // "a3828d19-..."
console.log(account.timeZone);            // "America/New_York"
console.log(account.isAdminRole);         // true
console.log(account.account.paymentPlan); // "pro"

Cancel a Request

Pass an AbortSignal to cancel in-flight requests:

const controller = new AbortController();

// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);

const result = await truelist.email.validate("[email protected]", {
  signal: controller.signal,
});

Configuration

const truelist = new Truelist("your-api-key", {
  baseUrl: "https://api.truelist.io", // API base URL (default)
  timeout: 30000,                      // Request timeout in ms (default: 30000)
  maxRetries: 2,                       // Max retries on failure (default: 2)
});

Retries and Rate Limiting

The SDK automatically retries failed requests with exponential backoff:

• Retried status codes: 429 (rate limit), 500, 502, 503, 504
• Retried errors: Network failures, timeouts
• Backoff: 500ms, 1000ms, 2000ms (with jitter)
• Retry-After: The SDK respects the Retry-After header on 429 responses

Set maxRetries: 0 to disable retries entirely.

Error Handling

All errors extend TruelistError:

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

try {
  const result = await truelist.email.validate("[email protected]");
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid API key (401)
    console.error("Bad API key");
  } else if (error instanceof RateLimitError) {
    // Rate limited (429) — retries exhausted
    console.error("Rate limited, retry after:", error.retryAfter);
  } else if (error instanceof ApiError) {
    // Other API error (4xx/5xx)
    console.error("API error:", error.status, error.body);
  } else if (error instanceof TruelistError) {
    // Timeout, network error, or cancelled request
    console.error("Request failed:", error.message);
  }
}

Error Classes

| Class | Status | Description | |-------|--------|-------------| | AuthenticationError | 401 | Invalid or missing API key | | RateLimitError | 429 | Rate limit exceeded (includes retryAfter if available) | | ApiError | varies | Any other HTTP error (includes status and body) | | TruelistError | - | Base class: timeout, network, or cancellation errors |

TypeScript Types

All types are exported for direct use:

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

ValidationState

"ok" | "email_invalid" | "risky" | "unknown" | "accept_all"

ValidationSubState

"email_ok" | "accept_all" | "is_disposable" | "is_role" | "failed_smtp_check" | "failed_mx_check" | "failed_spam_trap" | "failed_no_mailbox" | "failed_greylisted" | "failed_syntax_check" | "unknown_error"

ValidationResult

| Property | Type | Description | |----------|------|-------------| | email | string | The email address validated | | domain | string | Domain part of the email | | canonical | string | Canonical (local) part of the email | | mxRecord | string \| null | MX record for the domain | | firstName | string \| null | First name (if detected) | | lastName | string \| null | Last name (if detected) | | state | ValidationState | Overall validation state | | subState | ValidationSubState | Detailed sub-state | | verifiedAt | string | ISO timestamp of verification | | suggestion | string \| null | Did-you-mean suggestion |

Convenience Methods

| Function | Description | |----------|-------------| | isValid(result) | true if state === "ok" | | isInvalid(result) | true if state === "email_invalid" | | isDisposable(result) | true if subState === "is_disposable" | | isRole(result) | true if subState === "is_role" |

Edge Runtime Support

This SDK uses the standard fetch API with no Node.js-specific dependencies. It works in:

• Node.js 18+
• Vercel Edge Functions
• Cloudflare Workers
• Deno

// Cloudflare Worker example
export default {
  async fetch(request: Request): Promise<Response> {
    const truelist = new Truelist(env.TRUELIST_API_KEY);
    const result = await truelist.email.validate("[email protected]");
    return Response.json(result);
  },
};

API Reference

new Truelist(apiKey, options?)

Create a new Truelist client.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | apiKey | string | Yes | Your Truelist API key | | options.baseUrl | string | No | API base URL. Default: https://api.truelist.io | | options.timeout | number | No | Request timeout in ms. Default: 30000 | | options.maxRetries | number | No | Max retry attempts. Default: 2 |

truelist.email.validate(email, options?)

Validate an email address.

Returns Promise<ValidationResult>.

truelist.account.get()

Get account information.

Returns Promise<AccountInfo>.

Getting Started

Sign up for a free Truelist account to get your API key. The free plan includes 100 validations and 10 enhanced credits — no credit card required.

License

MIT