SDK Reference

The official Spamidate SDK provides a type-safe, batteries-included client for TypeScript and JavaScript applications.

Installation

npm

npm install @spamidate/sdk

yarn

yarn add @spamidate/sdk

pnpm

pnpm add @spamidate/sdk

Quick Start

import { Spamidate } from '@spamidate/sdk';

const client = new Spamidate({ apiKey: process.env.SPAMIDATE_API_KEY });

// Validate single email
const result = await client.validate('user@example.com');
console.log(result.isValid, result.score);

// Get classification decision
const classification = await client.classify('user@example.com', 'signup');
console.log(classification.decision); // 'accept' | 'reject' | 'review'

---

Client Configuration

const client = new Spamidate({
  // Required
  apiKey: 'spm_live_...',

  // Optional
  baseUrl: 'https://api.spamidate.com',
  timeout: 30000,
  retries: 2,
});

Option	Type	Default	Description
apiKey	string	Required	Your Spamidate API key
baseUrl	string	https://api.spamidate.com	API base URL
timeout	number	30000	Request timeout (ms)
retries	number	2	Retry attempts for failed requests

---

Methods

validate(email, options?)

Validate a single email address.

const result = await client.validate('user@example.com');

// With options
const result = await client.validate('user@example.com', {
  quickMode: true,
  bypassCache: false,
});

Options:

Option	Type	Default	Description
quickMode	boolean	false	Skip expensive checks
bypassCache	boolean	false	Force fresh validation

Returns: EmailValidationResult

interface EmailValidationResult {
  email: string;
  severity: 'valid' | 'warning' | 'invalid';
  isValid: boolean;
  score: number;
  deliverabilityScore?: number;
  checks: ValidationChecks;
  recommendations: string[];
  timestamp: string;
  processingTime: number;
}

---

validateBatch(emails, options?)

Validate multiple emails in one request (max 100).

const results = await client.validateBatch([
  'user1@example.com',
  'user2@example.com',
]);

console.log(`Valid: ${results.valid}/${results.total}`);

// Filter valid emails
const validEmails = results.results
  .filter(r => r.isValid)
  .map(r => r.email);

Returns: BatchValidationResponse

interface BatchValidationResponse {
  total: number;
  valid: number;
  invalid: number;
  warning: number;
  results: EmailValidationResult[];
  processingTime: number;
  timestamp: string;
}

---

classify(email, context?)

Get a simple accept/reject/review decision.

const classification = await client.classify('user@example.com', 'signup');

switch (classification.decision) {
  case 'accept':
    await createUser(email);
    break;
  case 'reject':
    showError(classification.reason);
    break;
  case 'review':
    await flagForReview(email, classification.warnings);
    break;
}

Contexts:

Context	Accept Threshold	Use Case
signup	Score >= 70	User registration
marketing	Score >= 80	Email campaigns
transactional	Score >= 50	Order confirmations
crm-import	Score >= 60	Database imports
list-cleaning	Score >= 70	List hygiene

Returns: EmailClassification

interface EmailClassification {
  decision: 'accept' | 'reject' | 'review';
  confidence: number;
  reason: string;
  blockingIssues: string[];
  warnings: string[];
  suggestedCorrection?: string;
}

---

getUsage()

Get current API usage and quota information.

const usage = await client.getUsage();

console.log(`${usage.quota.percentage}% used`);
console.log(`${usage.quota.remaining} remaining`);
console.log(`Plan: ${usage.plan.name}`);

if (usage.quota.inGracePeriod) {
  console.warn('In grace period - upgrade plan');
}

Returns: UsageResponse

Tip

The usage endpoint is free and doesn’t count against your quota.

---

Helper Methods

Quick boolean checks for common validations:

// Quick validity check
const isValid = await client.isValid('user@example.com');
// Returns: boolean

// Check if disposable
const isDisposable = await client.isDisposable('user@tempmail.com');
// Returns: boolean

// Check if role-based
const isRoleBased = await client.isRoleBased('info@company.com');
// Returns: boolean

---

Error Handling

The SDK provides typed error classes for each error type:

import {
  Spamidate,
  SpamidateError,
  AuthenticationError,
  RateLimitError,
  QuotaExceededError,
  ValidationInputError,
  NetworkError,
  TimeoutError,
  ServerError,
} from '@spamidate/sdk';

try {
  const result = await client.validate('user@example.com');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  }

  if (error instanceof RateLimitError) {
    console.log(`Retry after ${error.retryAfter} seconds`);
    await sleep(error.retryAfter * 1000);
    // Retry...
  }

  if (error instanceof QuotaExceededError) {
    console.error('Monthly quota exhausted');
  }

  if (error instanceof ValidationInputError) {
    console.error('Invalid input:', error.message);
  }

  if (error instanceof TimeoutError) {
    console.error('Request timed out');
  }

  if (error instanceof NetworkError) {
    console.error('Network connectivity issue');
  }

  if (error instanceof ServerError) {
    console.error('Server error');
  }

  // All errors have isRetryable property
  if (error instanceof SpamidateError && error.isRetryable) {
    // Safe to retry
  }
}

Error Class Reference

Error Class	HTTP Status	isRetryable	Description
AuthenticationError	401	false	Invalid or missing API key
RateLimitError	429	true	Rate limit exceeded
QuotaExceededError	429	false	Monthly quota exhausted
ValidationInputError	400	false	Invalid request parameters
NetworkError	-	true	Network connectivity failure
TimeoutError	-	true	Request timeout
ServerError	5xx	true	Server-side error

---

Common Patterns

Signup Form Validation

async function validateSignup(email: string) {
  const result = await client.validate(email);

  // Block disposable emails
  if (result.checks.disposable?.status === 'fail') {
    return { error: 'Disposable emails not allowed' };
  }

  // Suggest typo correction
  if (result.checks.typoSuggestion?.metadata?.suggestion) {
    return {
      error: `Did you mean ${result.checks.typoSuggestion.metadata.suggestion}?`,
      suggestion: result.checks.typoSuggestion.metadata.suggestion,
    };
  }

  // Require minimum score
  if (result.score < 50) {
    return { error: 'Unable to verify this email address' };
  }

  return { valid: true, score: result.score };
}

Batch Processing with Chunking

async function processLargeList(emails: string[]) {
  const results = [];
  const batchSize = 100;

  for (let i = 0; i < emails.length; i += batchSize) {
    const batch = emails.slice(i, i + batchSize);
    const response = await client.validateBatch(batch);
    results.push(...response.results);

    console.log(`Processed ${Math.min(i + batchSize, emails.length)}/${emails.length}`);
  }

  return {
    valid: results.filter(r => r.isValid),
    invalid: results.filter(r => !r.isValid),
  };
}

Retry with Exponential Backoff

async function validateWithRetry(email: string, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.validate(email);
    } catch (error) {
      if (error instanceof RateLimitError && attempt < maxRetries - 1) {
        await sleep(error.retryAfter * 1000);
        continue;
      }
      if (error instanceof SpamidateError && error.isRetryable && attempt < maxRetries - 1) {
        await sleep(Math.pow(2, attempt) * 1000);
        continue;
      }
      throw error;
    }
  }
}

Caching Results

const cache = new Map<string, EmailValidationResult>();

async function validateWithCache(email: string) {
  const key = email.toLowerCase();

  if (cache.has(key)) {
    return cache.get(key)!;
  }

  const result = await client.validate(email);
  cache.set(key, result);

  // Clear after 24 hours
  setTimeout(() => cache.delete(key), 24 * 60 * 60 * 1000);

  return result;
}

---

CLI Usage

The SDK includes a command-line interface:

# Set your API key
export SPAMIDATE_API_KEY=spm_live_...

# Validate single email
spamidate validate user@example.com

# Quick validation
spamidate validate user@example.com --quick

# Get classification
spamidate classify user@example.com --context signup

# Validate from file
spamidate batch emails.txt --output results.json

# Extract valid emails only
spamidate batch emails.txt --valid-only > valid.txt

# Check usage
spamidate usage

# Output as JSON
spamidate validate user@example.com --json

CLI Commands

Command	Description
validate <email>	Validate a single email
classify <email>	Get accept/reject/review decision
batch <file>	Validate emails from file
usage	Show API usage and quota
help	Show help message

CLI Options

Option	Description
--quick, -q	Skip expensive checks
--json, -j	Output raw JSON
--context <type>	Classification context
--output <file>	Write results to file
--valid-only	Only output valid emails
--invalid-only	Only output invalid emails

Exit Codes

Code	Meaning
0	Success / Valid email
1	Invalid email / Error
2	Review needed

---

TypeScript Support

The SDK is written in TypeScript and exports all types:

import type {
  EmailValidationResult,
  BatchValidationResponse,
  EmailClassification,
  UsageResponse,
  ValidationCheck,
  ValidationChecks,
} from '@spamidate/sdk';

Full type definitions are available in the package.