VerifyForge
VerifyForge

Python SDK

Official Python client library

Package: verifyforge

Installation

pip install verifyforge

Quick Start

from verifyforge import VerifyForge

client = VerifyForge(api_key="your_api_key_here")

result = client.validate("user@example.com")

if result.data.is_valid:
    print(f"✓ Email is valid!")
    print(f"Reachability: {result.data.reachability}")

Single Email Validation

result = client.validate("test@example.com")

print(f"Valid: {result.data.is_valid}")
print(f"Disposable: {result.data.disposable}")
print(f"Role Account: {result.data.role_account}")
print(f"Reachability: {result.data.reachability}")

# Check MX records
for mx in result.data.mx_records_list:
    print(f"MX: {mx.exchange} (priority: {mx.priority})")

Bulk Email Validation

Validate up to 100 emails in a single request:

emails = [
    "user1@example.com",
    "user2@example.com",
    "user3@example.com",
]

result = client.validate_bulk(emails)

print(f"Total: {result.summary.total}")
print(f"Duplicates removed: {result.summary.duplicates_removed}")
print(f"Credits used: {result.credits_used}")

for item in result.results:
    status = "✓" if item.is_valid else "✗"
    print(f"{status} {item.email}")

Error Handling

from verifyforge import (
    VerifyForge,
    AuthenticationError,
    InsufficientCreditsError,
    ValidationError,
)

client = VerifyForge(api_key="your_api_key")

try:
    result = client.validate("test@example.com")
except AuthenticationError:
    print("Invalid API key")
except InsufficientCreditsError:
    print("Not enough credits")
except ValidationError as e:
    print(f"Validation error: {e.message}")

Context Manager

Automatically manages the session:

with VerifyForge(api_key="your_api_key") as client:
    result = client.validate("test@example.com")
    print(f"Valid: {result.data.is_valid}")

Configuration

client = VerifyForge(
    api_key="your_api_key",
    base_url="https://verifyforge.com",  # Optional
    timeout=30,  # Optional, in seconds
)

Type Hints

Full type hints for better IDE support:

from verifyforge import ValidationResponse, BulkValidationResponse

result: ValidationResponse = client.validate("test@example.com")
bulk_result: BulkValidationResponse = client.validate_bulk(emails)

API Reference

Constructor

VerifyForge(api_key: str, base_url: str = "https://verifyforge.com", timeout: int = 30)

Parameters:

  • api_key (str): Your API key
  • base_url (str, optional): Base URL, defaults to "https://verifyforge.com"
  • timeout (int, optional): Timeout in seconds, defaults to 30

Methods

validate(email: str) -> ValidationResponse

Validate a single email address.

Raises:

  • ValidationError: Invalid email format
  • InsufficientCreditsError: Insufficient credits
  • APIError: Validation failed

validate_bulk(emails: List[str]) -> BulkValidationResponse

Validate up to 100 email addresses.

Raises:

  • ValidationError: Invalid email list or exceeds 100 emails
  • InsufficientCreditsError: Insufficient credits
  • APIError: Validation failed

Response Types

ValidationResponse

@dataclass
class ValidationResponse:
    success: bool
    data: ValidationResult
    credits_used: int
    remaining_credits: int
    validation_duration: Optional[int]
    api_version: Optional[str]

ValidationResult

@dataclass
class ValidationResult:
    email: str
    is_valid: bool
    syntax: SyntaxValidation
    mx_records_list: List[MXRecord]
    smtp: SMTPAnalysis
    disposable: bool
    role_account: bool
    free_provider: bool
    reachability: str  # "safe", "risky", "invalid", "unknown"
    suggestion: Optional[str]
    gravatar: Optional[Gravatar]

Exceptions

All exceptions inherit from VerifyForgeError:

  • AuthenticationError: Invalid API key (401)
  • InsufficientCreditsError: Insufficient credits (402)
  • ValidationError: Request validation failed (400)
  • RateLimitError: Rate limit exceeded (429)
  • APIError: General API error (5xx)

Requirements

  • Python 3.8+
  • requests >= 2.31.0

Links