BigShield

Multi-signal email validation SDK. Detect fake signups, burner emails, and disposable domains before they drain your AI budget.

Get your API key | Documentation | Live Demo

Install

npm install bigshield

Quick Start

import { BigShield } from 'bigshield';

const shield = new BigShield('ev_live_...');

const result = await shield.validate('[email protected]');

if (result.recommendation === 'reject') {
  // Burner or fake email — don't provision resources
  throw new Error('Please use a valid email address');
}

// Safe to create account

Usage

Validate a single email

const result = await shield.validate('[email protected]');

console.log(result.risk_score);      // 0-100 (higher = safer)
console.log(result.risk_level);      // 'very_low' | 'low' | 'medium' | 'high' | 'very_high'
console.log(result.recommendation);  // 'accept' | 'review' | 'reject'
console.log(result.signals);         // Array of signal results

Signup flow example

import { BigShield } from 'bigshield';

const shield = new BigShield('ev_live_...');

app.post('/signup', async (req, res) => {
  const { email, password } = req.body;

  // Validate before creating account
  const result = await shield.validate(email);

  if (result.recommendation === 'reject') {
    return res.status(400).json({
      error: 'Please use a valid email address'
    });
  }

  if (result.recommendation === 'review') {
    // Flag for manual review, but allow signup
    await flagForReview(email, result);
  }

  // Safe — create account and provision resources
  const user = await createAccount(email, password);
  await allocateTokens(user.id, plan.tokens);

  return res.json({ ok: true });
});

Batch validation

Validate up to 100 emails in a single request:

const { results, total, completed } = await shield.batchValidate([
  '[email protected]',
  '[email protected]',
  '[email protected]',
]);

const blocked = results.filter(r => r.recommendation === 'reject');
console.log(`Blocked ${blocked.length} of ${total} emails`);

Poll for async results

Tier 2 signals (SMTP verification, etc.) run asynchronously. Poll for completion:

const initial = await shield.validate('[email protected]');

if (initial.status === 'partial') {
  // Wait for all signals to complete
  const final = await shield.waitForCompletion(initial.id, {
    interval: 1000,   // poll every 1s
    maxAttempts: 30,   // give up after 30s
  });

  console.log(final.risk_score); // Updated with all signals
}

Check usage

const usage = await shield.getUsage();

console.log(`${usage.usage.total} / ${usage.usage.limit} validations used`);
console.log(`Plan: ${usage.plan}`);

Configuration

// Simple — just pass your API key
const shield = new BigShield('ev_live_...');

// Advanced options
const shield = new BigShield({
  apiKey: 'ev_live_...',
  baseUrl: 'https://bigshield.app',  // default
  timeout: 30000,                     // request timeout in ms
  retries: 2,                         // retry on 5xx errors
});

Response Format

{
  "id": "val_a1b2c3d4",
  "email": "[email protected]",
  "status": "completed",
  "risk_score": 82,
  "risk_level": "low",
  "recommendation": "accept",
  "signals": [
    {
      "name": "email-format",
      "tier": "tier1",
      "score_impact": 10,
      "confidence": 1.0,
      "description": "Email format is valid",
      "duration_ms": 1
    }
  ],
  "created_at": "2025-01-01T00:00:00Z"
}

Error Handling

import { BigShield, AuthError, RateLimitError, BigShieldError } from 'bigshield';

try {
  await shield.validate('[email protected]');
} catch (err) {
  if (err instanceof AuthError) {
    // Invalid or missing API key (401)
  } else if (err instanceof RateLimitError) {
    // Rate limit exceeded (429)
    console.log(`Retry after ${err.retryAfter} seconds`);
  } else if (err instanceof BigShieldError) {
    // Other API error
    console.log(err.code, err.status, err.details);
  }
}

Plans

| Plan | Validations/mo | Rate Limit | Batch Size | |------|---------------|------------|------------| | Free | 100 | 10/min | 5 | | Starter ($29/mo) | 5,000 | 60/min | 25 | | Pro ($99/mo) | 50,000 | 200/min | 100 | | Enterprise | Custom | 1,000/min | 100 |

Sign up for free — no credit card required.

License

MIT