# Truval

Machine-readable API instructions for LLMs and agents.
Primary API: https://api.truval.dev
OpenAPI: https://api.truval.dev/openapi.json
MCP server: https://mcp.truval.dev/mcp
MCP tool schema: https://mcp.truval.dev/openapi.json

## Authentication
- All HTTP API requests require header: Authorization: Bearer sk_live_...
- Content-Type for JSON requests: application/json
- API keys are issued in dashboard: https://dash.truval.dev

## HTTP API
### POST /v1/email/verify
- URL: https://api.truval.dev/v1/email/verify
- Body schema:
  - email: string (required)

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

## Response schema
- email: string
- valid: boolean
- status: deliverable | undeliverable | unknown | catch_all | invalid
- confidence: number (0..1)
- failed_check: syntax | disposable | no_mx | smtp | null
- disposable: boolean
- role: boolean
- free_provider: boolean
- catch_all: boolean
- smtp_blocked: boolean
- mx_found: boolean
- mx_host: string | null
- suggestion: string | null
- latency_ms: number

## Status interpretation
- deliverable: mailbox accepted by SMTP probe
- undeliverable: mailbox rejected by SMTP probe
- unknown: mailbox could not be confirmed
- catch_all: domain accepts all recipients; mailbox-level certainty unavailable
- invalid: failed syntax/disposable/MX validation

## Major provider behavior (important)
Gmail, Outlook, Yahoo, and similar providers often block third-party SMTP probing.
Expected result pattern:
- smtp_blocked: true
- status: unknown
- confidence: 0.75
This is expected behavior, not an integration error.

## Error and rate-limit pattern
- 401: missing/invalid API key
- 400: malformed request body
- 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"
}

Rate limits by plan:
- free: 10 requests/minute
- builder: 100 requests/minute
- scale: 1000 requests/minute

## Agent usage patterns
- Single-check flow: call verify endpoint once per user-entered email before signup/send.
- Batch flow: queue requests, respect per-minute tier limit, add jittered retries on 429.
- Retry policy:
  - retry on: 429, transient 5xx, network timeout
  - do not retry on: deterministic invalid input (syntax/disposable/no_mx)
- Decision policy:
  - valid=true: proceed
  - status=undeliverable or invalid: block or request alternate email
  - status=unknown with smtp_blocked=true: allow with caution and optional secondary verification
  - suggestion!=null: present corrected domain to user

## MCP quick start
- Endpoint: https://mcp.truval.dev/mcp
- Transport: JSON-RPC 2.0 over HTTP POST
- Tool exposed: verify_email
- Tool args schema:
  - email: string (required)
- Authorization header is required on MCP requests and forwarded upstream.

Minimal tool call params:
{
  "name": "verify_email",
  "arguments": {
    "email": "user@example.com"
  }
}

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

## Full reference
For complete examples (curl, TypeScript, Python, LangChain, CrewAI, Vercel AI SDK, and full MCP JSON-RPC), read:
https://truval.dev/llms-full.txt