Trueform Node.js SDK

The official Node.js client for the Trueform email validation API. Validate email format, disposable and freemail providers, common domain typos, and mail routing without an API key.

Documentation | API reference | npm | Changelog | Issues

Features

• Typed results and error classes
• ESM and CommonJS builds with zero runtime dependencies
• Built-in retries for connection failures, timeouts, rate limits, and server errors
• Per-request timeouts and AbortSignal support

Install

npm install trueform-node

The SDK supports Node.js 20 and newer. It has no runtime dependencies and does not require an API key.

Quickstart

import Trueform from 'trueform-node'

const trueform = new Trueform()

const validation = await trueform.validations.create({
  email: 'user@example.com',
})

if (validation.is_deliverable) {
  console.log('Email looks good')
}

The client uses a resource-based interface:

trueform.validations.create(params, options)

Handle validation results

const result = await trueform.validations.create({ email })

if (result.did_you_mean) {
  console.log(`Did you mean ${result.did_you_mean}?`)
}

if (result.is_disposable) {
  console.log('Ask for a permanent email address')
}

is_deliverable is a domain-level verdict. It does not prove that a specific mailbox exists.

Configure the client

const trueform = new Trueform({
  timeout: 5_000,
  maxRetries: 2,
})

Override options for one request:

const controller = new AbortController()

const result = await trueform.validations.create(
  { email: 'user@example.com' },
  {
    signal: controller.signal,
    timeout: 2_000,
    maxRetries: 0,
  },
)

The client retries connection failures, timeouts, rate limits, and server errors. A Retry-After response header controls the delay when present.

Errors

import Trueform, {
  TrueformInvalidRequestError,
  TrueformRateLimitError,
} from 'trueform-node'

const trueform = new Trueform()

try {
  await trueform.validations.create({ email: 'user@example.com' })
} catch (error) {
  if (error instanceof TrueformRateLimitError) {
    console.error(`Retry after ${error.retryAfter}ms`)
  } else if (error instanceof TrueformInvalidRequestError) {
    console.error(error.message)
  } else {
    throw error
  }
}

Exported errors:

• TrueformError
• TrueformAPIError
• TrueformInvalidRequestError
• TrueformRateLimitError
• TrueformConnectionError
• TrueformTimeoutError

API errors expose code, status, and requestId when available.

CommonJS

const { Trueform } = require('trueform-node')

const trueform = new Trueform()

Development

npm install
npm run check

Read the contributing guide before opening a pull request. Report vulnerabilities through the process in the security policy.

Trueform SDKs

Platform	Registry	Source
Node.js	trueform-node on npm	GitHub
PHP	trueform/trueform on Packagist	GitHub
Ruby	trueform on RubyGems	GitHub
Python	trueform-cloud on PyPI	GitHub

License

MIT. See the license.