LangChain

Installation

npm install @langchain/core truval

Basic tool definition

import { tool } from '@langchain/core/tools'
import { z } from 'zod'

const verifyEmailTool = tool(
  async ({ email }) => {
    const res = await fetch('https://api.truval.dev/v1/email/verify', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.TRUVAL_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ email }),
    })
    return res.json()
  },
  {
    name: 'verify_email',
    description: 'Verify if an email address is real and deliverable. Returns valid, confidence score, and whether the address is disposable or a role address.',
    schema: z.object({
      email: z.string().email().describe('The email address to verify'),
    }),
  }
)

Using with an agent

import { ChatOpenAI } from '@langchain/openai'
import { createReactAgent } from '@langchain/langgraph/prebuilt'

const agent = createReactAgent({
  llm: new ChatOpenAI({ model: 'gpt-4o' }),
  tools: [verifyEmailTool],
})

const result = await agent.invoke({
  messages: [{ role: 'user', content: 'Is user@example.com a valid email?' }],
})

Filtering low-confidence results

const verifyEmailTool = tool(
  async ({ email, min_confidence = 0.7 }) => {
    const res = await fetch('https://api.truval.dev/v1/email/verify', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.TRUVAL_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ email }),
    })
    const data = await res.json()

    if (data.confidence < min_confidence) {
      return { ...data, recommendation: 'low confidence — consider rejecting' }
    }
    return data
  },
  {
    name: 'verify_email',
    description: 'Verify email deliverability with confidence scoring.',
    schema: z.object({
      email: z.string().email(),
      min_confidence: z.number().min(0).max(1).optional()
        .describe('Minimum confidence threshold (default: 0.7)'),
    }),
  }
)

Environment variables

TRUVAL_API_KEY=sk_live_...

Get your API key at dash.truval.dev.