# Truval LLM Full Reference

Canonical docs for AI agents integrating Truval email verification via HTTP API or MCP.
Primary API base: https://api.truval.dev
HTTP OpenAPI: https://api.truval.dev/openapi.json
MCP endpoint: https://mcp.truval.dev/mcp
MCP tool schema endpoint: https://mcp.truval.dev/openapi.json

## 1) Authentication

Required on all API and MCP requests:
- Authorization: Bearer sk_live_...

For HTTP API requests:
- Content-Type: application/json

Get keys at:
- https://dash.truval.dev

## 2) HTTP API Contract

Endpoint:
- POST https://api.truval.dev/v1/email/verify

Request JSON schema:
{
  "type": "object",
  "required": ["email"],
  "properties": {
    "email": { "type": "string", "description": "Email address to verify" }
  },
  "additionalProperties": false
}

Request example:
{
  "email": "user@example.com"
}

Success response JSON schema:
{
  "type": "object",
  "required": [
    "email",
    "valid",
    "status",
    "confidence",
    "failed_check",
    "disposable",
    "role",
    "free_provider",
    "catch_all",
    "smtp_blocked",
    "mx_found",
    "mx_host",
    "suggestion",
    "latency_ms"
  ],
  "properties": {
    "email": { "type": "string" },
    "valid": { "type": "boolean" },
    "status": {
      "type": "string",
      "enum": ["deliverable", "undeliverable", "unknown", "catch_all", "invalid"]
    },
    "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
    "failed_check": {
      "anyOf": [
        { "type": "string", "enum": ["syntax", "disposable", "no_mx", "smtp"] },
        { "type": "null" }
      ]
    },
    "disposable": { "type": "boolean" },
    "role": { "type": "boolean" },
    "free_provider": { "type": "boolean" },
    "catch_all": { "type": "boolean" },
    "smtp_blocked": { "type": "boolean" },
    "mx_found": { "type": "boolean" },
    "mx_host": { "anyOf": [{ "type": "string" }, { "type": "null" }] },
    "suggestion": { "anyOf": [{ "type": "string" }, { "type": "null" }] },
    "latency_ms": { "type": "number" }
  }
}

Example success response:
{
  "email": "user@example.com",
  "valid": true,
  "status": "deliverable",
  "confidence": 0.97,
  "failed_check": null,
  "disposable": false,
  "role": false,
  "free_provider": false,
  "catch_all": false,
  "smtp_blocked": false,
  "mx_found": true,
  "mx_host": "mail.example.com",
  "suggestion": null,
  "latency_ms": 187
}

## 3) Status Semantics

- deliverable: SMTP accepted mailbox.
- undeliverable: SMTP rejected mailbox.
- unknown: mailbox-level verification unavailable (timeout/greylist/provider blocks probing).
- catch_all: domain accepts all RCPT; mailbox-level certainty unavailable.
- invalid: failed syntax/disposable/no_mx checks.

Major-provider behavior:
- For Gmail/Outlook/Yahoo/iCloud-like domains, third-party SMTP probing may be blocked.
- Expected response pattern:
  - smtp_blocked=true
  - status=unknown
  - confidence=0.75
- Treat this as expected, not as API failure.

## 4) Error Contract

Common HTTP errors:
- 400 Invalid request body
- 401 Missing or invalid API key
- 429 Rate limit exceeded
- 404 Unknown route

401 missing key shape:
{
  "error": "missing_api_key",
  "message": "No Authorization header provided.",
  "action": "Include your API key as: Authorization: Bearer sk_live_...",
  "docs": "https://docs.truval.dev/api/email-verify#authentication"
}

401 invalid key shape:
{
  "error": "invalid_api_key",
  "message": "API key not found or revoked.",
  "action": "Generate a new key at https://dash.truval.dev.",
  "docs": "https://docs.truval.dev/api/email-verify#authentication"
}

400 invalid request shape:
{
  "error": "invalid_request",
  "message": "Request body must be JSON with an email field.",
  "action": "Send: {\"email\":\"user@example.com\"}",
  "docs": "https://docs.truval.dev/api/email-verify#request"
}

429 shape:
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit of 100 req/min exceeded.",
  "action": "Wait until reset_at before retrying.",
  "limit": 10,
  "window": "1m",
  "reset_at": "2026-01-01T00:00:00.000Z",
  "docs": "https://docs.truval.dev/api/email-verify#rate-limits"
}

404 shape:
{
  "error": "not_found",
  "message": "The requested endpoint does not exist.",
  "action": "Use POST /v1/email/verify or inspect https://api.truval.dev/openapi.json.",
  "docs": "https://docs.truval.dev/api/email-verify#not-found"
}

Plan rate limits:
- free: 10 req/min
- builder: 100 req/min
- scale: 1000 req/min

Pricing:
- free: 500/mo, EUR 0
- builder: 5,000/mo, EUR 9 (+ EUR 0.002 overage per call)
- scale: 100,000/mo, EUR 49 (+ EUR 0.0012 overage per call)

## 5) Integration Examples

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

### 5.2 TypeScript (fetch)
import "dotenv/config";

const API_KEY = process.env.TRUVAL_API_KEY!;

async function verifyEmail(email: string) {
  const res = await fetch("https://api.truval.dev/v1/email/verify", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ email }),
  });

  if (!res.ok) {
    throw new Error(`Truval error ${res.status}: ${await res.text()}`);
  }

  const data = await res.json();
  return data;
}

const result = await verifyEmail("user@example.com");
console.log(result);

### 5.3 Python (requests)
import os
import requests

API_KEY = os.environ["TRUVAL_API_KEY"]

def verify_email(email: str) -> dict:
    resp = requests.post(
        "https://api.truval.dev/v1/email/verify",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={"email": email},
        timeout=10,
    )
    resp.raise_for_status()
    return resp.json()

print(verify_email("user@example.com"))

### 5.4 LangChain tool wrapper (Python)
import os
import requests
from langchain.tools import tool

API_KEY = os.environ["TRUVAL_API_KEY"]

@tool("truval_verify_email")
def truval_verify_email(email: str) -> str:
    """Verify whether an email is deliverable."""
    resp = requests.post(
        "https://api.truval.dev/v1/email/verify",
        headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
        json={"email": email},
        timeout=10,
    )
    resp.raise_for_status()
    return resp.text

### 5.5 CrewAI tool (Python)
import os
import requests
from crewai.tools import BaseTool

class TruvalVerifyEmailTool(BaseTool):
    name: str = "truval_verify_email"
    description: str = "Verify if an email is valid and deliverable using Truval."

    def _run(self, email: str) -> str:
        api_key = os.environ["TRUVAL_API_KEY"]
        resp = requests.post(
            "https://api.truval.dev/v1/email/verify",
            headers={
                "Authorization": f"Bearer {api_key}",
                "Content-Type": "application/json",
            },
            json={"email": email},
            timeout=10,
        )
        resp.raise_for_status()
        return resp.text

### 5.6 Vercel AI SDK tool (TypeScript)
import { tool } from "ai";
import { z } from "zod";

const truvalVerifyEmail = tool({
  description: "Verify whether an email is valid and deliverable",
  inputSchema: z.object({
    email: z.string().email(),
  }),
  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 }),
    });

    if (!res.ok) {
      throw new Error(`Truval error ${res.status}: ${await res.text()}`);
    }
    return res.json();
  },
});

## 6) MCP Contract

MCP transport:
- HTTP POST
- JSON-RPC 2.0
- endpoint: https://mcp.truval.dev/mcp
- requires Authorization: Bearer sk_live_...

Supported MCP methods:
- tools/list
- tools/call

Exposed tool:
- name: verify_email
- input schema:
  {
    "type": "object",
    "required": ["email"],
    "properties": {
      "email": {
        "type": "string",
        "description": "The email address to verify"
      }
    }
  }

### 6.1 MCP tools/list example
curl -sS -X POST "https://mcp.truval.dev/mcp" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"tools/list"
  }'

### 6.2 MCP tools/call example
curl -sS -X POST "https://mcp.truval.dev/mcp" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"verify_email",
      "arguments":{"email":"user@example.com"}
    }
  }'

Expected `tools/call` result payload:
- result.content[0].type = "text"
- result.content[0].text = JSON string of verification response

MCP error patterns:
- Missing Authorization header -> JSON-RPC error code -32001, HTTP 401
- Upstream API failure -> JSON-RPC error code -32002, HTTP mirrors upstream status
- Invalid upstream JSON -> JSON-RPC error code -32003, HTTP 502
- Invalid method -> JSON-RPC error code -32601
- Invalid params -> JSON-RPC error code -32602

MCP error example (missing Authorization):
{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32001,
    "message": "Unauthorized",
    "data": {
      "reason": "Missing Authorization header",
      "action": "Provide Authorization: Bearer sk_live_... in MCP client headers.",
      "docs": "https://docs.truval.dev/api/email-verify#authentication"
    }
  }
}

Cursor MCP config:
{
  "mcpServers": {
    "truval": {
      "url": "https://mcp.truval.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${TRUVAL_API_KEY}"
      }
    }
  }
}

## 7) Agent Decision Logic (Recommended)

Given result object R:

1) If R.valid == true:
   - accept address.

2) Else if R.status in ["invalid", "undeliverable"]:
   - reject or request alternative address.
   - if R.suggestion != null, prompt user with corrected domain.

3) Else if R.status == "unknown":
   - if R.smtp_blocked == true and R.confidence >= 0.75:
     - allow with caution (e.g., require double opt-in).
   - otherwise:
     - treat as unconfirmed and trigger fallback verification flow.

4) Else if R.status == "catch_all":
   - accept conditionally and rely on downstream engagement signals.

## 8) Reliability Patterns

- Retry: transient network failures, 5xx, and 429 only.
- Backoff: exponential with jitter; honor `reset_at` on 429 when present.
- Avoid retry loops for deterministic failures (`invalid`, `undeliverable`, failed_check in syntax/disposable/no_mx).
- Persist raw response fields to preserve explainability for later decisions.

## 9) Canonical URLs

- Summary reference: https://truval.dev/llms.txt
- Full reference: https://truval.dev/llms-full.txt
- API OpenAPI: https://api.truval.dev/openapi.json
- MCP tool schema endpoint: https://mcp.truval.dev/openapi.json