Quick start

1. Get your API key

Sign up at dash.truval.dev — free tier includes 500 verification units per UTC calendar month (see monthly quota), no credit card required.

2. Give your agent the ability to verify

When an AI agent needs to verify an email address before sending a message, creating an account, or saving data to a CRM, it should call this endpoint:

curl https://api.truval.dev/v1/email/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'

Use the official SDK

From Node 18+ or any runtime with fetch:

npm install truval

import { createClient } from 'truval'

const truval = createClient(process.env.TRUVAL_API_KEY!)
const result = await truval.verify('user@example.com')

Full API surface (batch, streaming, management client, rate-limit retries): TypeScript / JavaScript SDK.

3. How your agent should read the response

Abbreviated response below — fields failed_check, free_provider, catch_all, mx_found, and mx_host are omitted for brevity. See the full response schema for every field.

{
  "email": "user@example.com",
  "valid": true,
  "status": "deliverable",
  "confidence": 0.97,
  "disposable": false,
  "role": false,
  "smtp_blocked": false,
  "suggestion": null,
  "latency_ms": 187
}

Field	What it means
`valid`	`true` for deliverable or catch-all SMTP outcomes; `false` for invalid, undeliverable, timeout, or unknown — use `status` and `confidence`, not `valid` alone
`status`	`deliverable` — SMTP confirmed. `unknown` — inconclusive (major providers / timeout / ambiguous SMTP on org mail). `invalid` / `undeliverable` — failed or rejected.
`confidence`	Ordinal 0–1 (not a probability). 0.97 = deliverable. 0.75 = `smtp_blocked` domain. 0.65 = catch-all. 0.50 = unknown with MX but SMTP inconclusive. 0.02 = undeliverable. See confidence ladder.
`catch_all`	`true` means the domain accepts any recipient. Treat with caution even if `valid` is `true`.
`smtp_blocked`	`true` for Gmail, Outlook, Yahoo — they block SMTP probing from all third parties. This is normal.
`suggestion`	Typo correction — `"gnail.com"` returns `"gmail.com"`

Agent Integration

Your agents can start verifying emails immediately using our supported integrations.

MCP (Cursor, Claude)

Create .cursor/mcp.json (or claude_desktop_config.json):

{
  "mcpServers": {
    "truval": {
      "url": "https://mcp.truval.dev/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_..."
      }
    }
  }
}

Vercel AI SDK

Define a tool with the ai package and the same HTTP API as above. Step-by-step agent examples: Vercel AI SDK.

npm install ai zod

import { tool } from 'ai'
import { z } from 'zod'

export const verifyEmailTool = tool({
  description:
    'Verify if an email address is real and deliverable. Returns valid, status, confidence, disposable, role, smtp_blocked, and typo suggestion.',
  parameters: z.object({
    email: z.string().email().describe('The email address to verify'),
  }),
  execute: 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()
  },
})

// generateText / streamText: tools: { verifyEmail: verifyEmailTool }

See the Integrations docs for MCP, LangChain, CrewAI, and webhooks.

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer sk_live_...

Keys are generated in your dashboard. In non-production environments you may also see sk_test_... keys; authentication works the same.

Rate limits

Per-minute caps apply per key (sliding window). On batch/stream routes, each email counts as one unit toward the limit. Full behavior: Email verify API — Rate limits.

Tier	Rate limit (req/min)
Free	10
Builder	100
Scale	1,000

Source & Repositories

Explore the public repositories for our core integration layers: