Trueform Node.js SDK

The official Node.js client for the Trueform email validation API.

Node.js SDK documentation | API reference

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: '[email protected]',
})

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: '[email protected]' },
  {
    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: '[email protected]' })
} 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 CONTRIBUTING.md before opening a pull request. Report vulnerabilities through the process in SECURITY.md.

License

MIT. See LICENSE.