README

Pure PHP SDK for the Soryxa email validation API. It has no third-party runtime dependencies and returns the current Soryxa /api/v1/validate contract, including policy, rollout, score-adjustment, usage, and response-header metadata.

Requirements

• PHP 8.1+
• ext-curl
• ext-json

Installation

composer require elvesora/soryxa-php

Quick Start

use Elvesora\SoryxaPHP\SoryxaClient;

$soryxa = new SoryxaClient(token: 'your-api-token');

$result = $soryxa->validate('user@example.com');

if ($result->isAllowed()) {
    // Email is valid; proceed.
}

if ($result->isBlocked()) {
    // Email failed validation or matched a block rule.
}

if ($result->needsReview()) {
    // Email needs manual review or safe fallback handling.
}

Configuration

$soryxa = new SoryxaClient(
    token: 'your-api-token',
    baseUrl: 'https://soryxa.elvesora.com',
    timeout: 30,
    retries: 0,
    retryDelay: 100,
    silentOnLimit: false,
);

Policy, Headers, And Correlation

validate() remains backward-compatible with validate($email). Current optional arguments are:

$result = $soryxa->validate(
    'user@example.com',
    'signup',
    [
        'X-Soryxa-Correlation-Id' => 'checkout-2026-06-21-001',
    ],
);

Method signature:

validate(
    string $email,
    ?string $policyKey = null,
    array $headers = [],
): ValidationResult

policy_key is optional and defaults server-side to default. The validation API accepts only email, optional policy_key, and optional headers.

Validation Result

$result->decision;          // allow, block, or review
$result->reasonCode;        // e.g. CLASSIFICATION_VALID
$result->decisionMessage;   // Internal/operator explanation
$result->customerMessage;   // Optional customer-safe message
$result->decisionReasons;   // Human-readable contributing reasons
$result->policyKey;         // Applied policy key, e.g. signup
$result->score;             // Final score, 0-100
$result->baseScore;         // Base score before adjustments, 0-100 or null
$result->scoreAdjustments;  // Policy score adjustments
$result->autoResolution;    // Auto-resolution metadata or null
$result->rollout;           // Rollout telemetry
$result->rawData;           // Raw upstream validation data or null
$result->upstream;          // Upstream health/degradation metadata or null
$result->data;              // Full response data, including future additive fields
$result->headers;           // Captured response headers
$result->usage;             // Usage summary

Helper methods mirror the properties:

$result->decision();
$result->reasonCode();
$result->decisionMessage();
$result->customerMessage();
$result->decisionReasons();
$result->policyKey();
$result->score();
$result->baseScore();
$result->scoreAdjustments();
$result->autoResolution();
$result->rollout();
$result->upstream();
$result->data();
$result->headers();

Response-header helpers:

$result->reasonCodeHeader(); // X-Soryxa-Reason-Code
$result->correlationId();    // X-Soryxa-Correlation-Id
$result->header('X-Soryxa-Correlation-Id');

Decision helpers:

$result->isAllowed();
$result->isBlocked();
$result->needsReview();
$result->isLimitExceeded();

Email And Checks

$result->email();
$result->username();
$result->domain();
$result->firstName();
$result->lastName();
$result->classification();

$result->isSyntaxValid();
$result->hasMxRecords();
$result->isSmtpValid();
$result->isDisposable();
$result->isFreeProvider();
$result->isRoleAccount();
$result->isBogus();
$result->isCatchAll();
$result->isDomainRegistered();
$result->isNewlyRegisteredDomain();

Each check is a Check object:

foreach ($result->checks as $check) {
    $check->name;
    $check->status;  // passed, failed, warning, or error
    $check->message;

    $check->passed();
    $check->failed();
    $check->isWarning();
    $check->isError();
}

$result->getCheck('Domain MX');
$result->passedChecks();
$result->failedChecks();
$result->warningChecks();

Usage Tracking

Every successful API response includes current usage:

$result->usage->remaining;
$result->usage->limit;
$result->usage->usagePercent();

Serialization

$array = $result->toArray();

toArray() includes all known fields, usage, headers, and any unknown future fields returned under data.

Silent Mode

By default, exceeding your API usage limit throws UsageLimitException. If silentOnLimit is true, validate() returns a local fallback result instead:

• decision is review
• reasonCode is LIMIT_EXCEEDED
• decisionMessage explains the quota state
• score and baseScore are 0
• isLimitExceeded() returns true
• isAllowed() returns false

This keeps application code running without silently approving traffic when quota is exhausted.

$result = $soryxa->validate('user@example.com');

if ($result->isLimitExceeded()) {
    // Log, alert, queue for review, or ask the customer to retry later.
}

Error Handling

use Elvesora\SoryxaPHP\SoryxaClient;
use Elvesora\SoryxaPHP\Exceptions\AuthenticationException;
use Elvesora\SoryxaPHP\Exceptions\SubscriptionException;
use Elvesora\SoryxaPHP\Exceptions\InsufficientScopeException;
use Elvesora\SoryxaPHP\Exceptions\ValidationException;
use Elvesora\SoryxaPHP\Exceptions\UsageLimitException;
use Elvesora\SoryxaPHP\Exceptions\ServerException;
use Elvesora\SoryxaPHP\Exceptions\ConnectionException;
use Elvesora\SoryxaPHP\Exceptions\SoryxaException;

try {
    $result = $soryxa->validate($email);
} catch (AuthenticationException $e) {
    // 401: invalid, expired, or missing token.
} catch (SubscriptionException $e) {
    // 402: no active subscription.
} catch (InsufficientScopeException $e) {
    // 403: token lacks required scope.
} catch (ValidationException $e) {
    // 422: invalid input.
} catch (UsageLimitException $e) {
    // 429: usage limit exceeded.
} catch (ServerException $e) {
    // 5xx: server-side error.
} catch (ConnectionException $e) {
    // Network failure, timeout, or invalid response.
} catch (SoryxaException $e) {
    // Other API error.
}

Every exception exposes:

$e->getMessage();
$e->getErrorCode();
$e->getStatusCode();
$e->getResponseBody();

Decision Reference

The decision field is always one of:

Common reason codes include:

Framework Integration

This package is framework-agnostic. For Laravel projects, use elvesora/soryxa-laravel, which provides a service provider, facade, and config file.

Development

Run the package contract checks:

composer test

License

MIT