@validkit/sdk

ValidKit TypeScript SDK

AI Agent Optimized Email Verification SDK

The official TypeScript/JavaScript SDK for ValidKit Email Verification API, designed specifically for AI agents with:

• 🚀 Agent-scale rate limits (1,000+ req/min)
• 📦 Bulk processing (10,000+ emails per request)
• ⚡ Token-optimized responses (80% smaller than competitors)
• 🔗 Multi-agent tracing capabilities
• 🔄 Async processing with webhooks

Installation

npm install @validkit/sdk
# or
yarn add @validkit/sdk
# or
pnpm add @validkit/sdk

Quick Start

import { ValidKit } from '@validkit/sdk'

const client = new ValidKit({
  api_key: 'your-api-key-here'
})

// Single email verification
const result = await client.verifyEmail('[e-mail]')
console.log(result.valid) // true/false

// Batch verification with progress tracking
const emails = ['[e-mail]', '[e-mail]', /* ... up to 10K emails */]
const results = await client.verifyBatch(emails, {
  format: 'compact', // 80% smaller responses
  progress_callback: (processed, total) => {
    console.log(`Progress: ${processed}/${total}`)
  }
})

AI Agent Examples

LangChain Integration

import { Tool } from 'langchain/tools'
import { ValidKit } from '@validkit/sdk'

class EmailValidationTool extends Tool {
  name = 'email_validator'
  description = 'Validate email addresses for deliverability'
  
  private client = new ValidKit({ api_key: process.env.VALIDKIT_API_KEY! })

  async _call(emails: string): Promise<string> {
    const emailList = emails.split(',').map(e => e.trim())
    
    const results = await this.client.verifyBatch(emailList, {
      format: 'compact', // Token efficient
      trace_id: `langchain-${Date.now()}`
    })
    
    const validEmails = Object.entries(results)
      .filter(([_, result]) => result.v)
      .map(([email]) => email)
    
    return `Valid emails: ${validEmails.join(', ')}`
  }
}

AutoGPT Plugin

import { ValidKit, ResponseFormat } from '@validkit/sdk'

export class EmailVerificationPlugin {
  private client: ValidKit

  constructor(apiKey: string) {
    this.client = new ValidKit({ 
      api_key: apiKey,
      user_agent: 'AutoGPT EmailVerification Plugin/1.0.0'
    })
  }

  async validateEmailList(emails: string[], agentId: string) {
    return await this.client.verifyBatch(emails, {
      format: ResponseFormat.COMPACT,
      trace_id: `autogpt-${agentId}`,
      progress_callback: (processed, total) => {
        console.log(`Agent ${agentId}: ${processed}/${total} emails processed`)
      }
    })
  }

  async validateLargeList(emails: string[], webhookUrl: string) {
    const job = await this.client.verifyBatchAsync(emails, {
      webhook_url: webhookUrl,
      format: ResponseFormat.COMPACT
    })
    
    return job.id
  }
}

Vercel AI SDK Integration

import { ValidKit } from '@validkit/sdk'
import { streamText } from 'ai'

const client = new ValidKit({ api_key: process.env.VALIDKIT_API_KEY! })

export async function validateAndProcess(emails: string[]) {
  // Validate emails first
  const results = await client.verifyBatch(emails, {
    format: 'compact'
  })
  
  const validEmails = Object.entries(results)
    .filter(([_, result]) => result.v)
    .map(([email]) => email)
  
  // Use validated emails in AI processing
  return streamText({
    model: openai('gpt-4'),
    prompt: `Process these validated emails: ${validEmails.join(', ')}`
  })
}

API Reference

ValidKit Constructor

const client = new ValidKit({
  api_key: string,           // Required: Your API key
  base_url?: string,         // Optional: API base URL
  timeout?: number,          // Optional: Request timeout (default: 30000ms)
  max_retries?: number,      // Optional: Max retry attempts (default: 3)
  default_chunk_size?: number, // Optional: Batch chunk size (default: 1000)
  user_agent?: string        // Optional: Custom user agent
})

Single Email Verification

await client.verifyEmail(email: string, options?: {
  format?: 'full' | 'compact',  // Response format
  trace_id?: string             // Multi-agent tracing
})

Full Format Response:

{
  success: true,
  email: "[e-mail]",
  valid: true,
  format: { valid: true },
  disposable: { valid: true, value: false },
  mx: { valid: true, records: ["mx1.example.com"] },
  smtp: { valid: true, code: 250 },
  processing_time_ms: 245,
  trace_id: "agent-123"
}

Compact Format Response (80% smaller):

{
  v: true,    // valid
  d: false,   // disposable
  // r: "reason" (only if invalid)
}

Batch Email Verification

await client.verifyBatch(emails: string[], options?: {
  format?: 'full' | 'compact',
  chunk_size?: number,
  progress_callback?: (processed: number, total: number) => void,
  trace_id?: string
})

Async Batch Processing (10K+ emails)

// Start async job
const job = await client.verifyBatchAsync(emails: string[], {
  format?: 'compact',
  webhook_url?: string,
  trace_id?: string
})

// Check job status
const status = await client.getBatchJob(job.id)

// Get results when complete
if (status.status === 'completed') {
  const results = await client.getBatchResults(job.id)
}

// Cancel if needed
await client.cancelBatchJob(job.id)

Error Handling

The SDK provides comprehensive error handling:

import { 
  ValidKitError, 
  RateLimitError, 
  BatchSizeError,
  InvalidAPIKeyError 
} from '@validkit/sdk'

try {
  const result = await client.verifyEmail('[e-mail]')
} catch (error) {
  if (error instanceof RateLimitError) {
    const retryDelay = error.getRetryDelay()
    console.log(`Rate limited. Retry in ${retryDelay}ms`)
  } else if (error instanceof BatchSizeError) {
    console.log('Batch too large, use verifyBatchAsync')
  } else if (error instanceof InvalidAPIKeyError) {
    console.log('Check your API key')
  }
}

Performance Benchmarks

ValidKit vs Competitors for 10,000 email verification:

Provider	Time	Response Size	Batch Support
ValidKit	4.8s	~2KB	✅ 10K emails
Competitor A	167 min	~8KB	❌ Sequential only
Competitor B	N/A	N/A	❌ No batch support

Rate Limits

ValidKit provides agent-scale rate limits:

• Free Tier: 1,000 requests/minute
• Pro Tier: 10,000 requests/minute
• Enterprise: 100,000+ requests/minute

Multi-Agent Tracing

Track requests across distributed agent systems:

// Agent 1
await client.verifyBatch(emails1, { 
  trace_id: 'workflow-abc-agent1' 
})

// Agent 2  
await client.verifyBatch(emails2, { 
  trace_id: 'workflow-abc-agent2' 
})

// All requests with same trace_id are correlated in logs

TypeScript Support

Full TypeScript definitions included:

import { 
  EmailVerificationResult,
  CompactResult,
  BatchJob,
  ResponseFormat 
} from '@validkit/sdk'

const result: EmailVerificationResult = await client.verifyEmail(
  '[e-mail]',
  { format: ResponseFormat.FULL }
)

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT License - see LICENSE file for details.

Support

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 📖 Docs: validkit.com/docs

---

Built for the AI agent era. Validate at the speed of thought. ⚡