bigshield 1.0.0

Multi-signal email validation SDK. Detect fake signups, burner emails, and disposable domains.

BigShield Python SDK

Multi-signal email validation SDK. Detect fake signups, burner emails, and disposable domains.

Install

pip install bigshield

Quick Start

from bigshield import BigShield

client = BigShield("ev_live_your_api_key")

# Validate a single email
result = client.validate("[e-mail]")
print(result.risk_score)    # 22
print(result.is_valid)      # True
print(result.recommendation)  # "accept"

# Check individual signals
for signal in result.signals:
    print(f"{signal.name}: {signal.score_impact} (confidence: {signal.confidence})")

Async Support

from bigshield import AsyncBigShield

client = AsyncBigShield("ev_live_your_api_key")
result = await client.validate("[e-mail]")

Validate with Context

Pass additional context for stronger fraud detection:

result = client.validate(
    "[e-mail]",
    wait=True,          # Wait for Tier 2 signals
    ip="203.0.113.1",   # Client IP
    fingerprint="fp_abc123",
    user_agent="Mozilla/5.0 ...",
)

Batch Validation

result = client.batch_validate([
    "[e-mail]",
    "[e-mail]",
    "[e-mail]",
])

for r in result.results:
    print(f"{r.email}: {r.risk_score} ({r.recommendation})")

Error Handling

from bigshield import BigShield, AuthError, RateLimitError

client = BigShield("ev_live_your_api_key")

try:
    result = client.validate("[e-mail]")
except AuthError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")

Configuration

client = BigShield(
    "ev_live_your_api_key",
    base_url="https://bigshield.app",  # Custom base URL
    timeout=15.0,                       # Request timeout in seconds
    retries=3,                          # Number of retries on server errors
)

Documentation

Full API docs at bigshield.app/docs.