Integrate Email Insights into Your PHP Application: A Developer’s Guide

4 min readOpportify Team

This guide explains how to integrate Email Insights into a PHP application using the official SDK. You will learn how to perform single analyses, launch batch jobs, handle exceptions safely, and implement best practices for configuration, logging, and security.

If you are new to the platform, start with the overview at /products/email-insights and the bulk validation features at /email-insights/bulk-email-validation. For compliance and security, see /security and /legal/gdpr-notice.

Requirements

  • PHP 8.1 or later
  • Composer
  • A valid API key

Install the SDK:

composer require opportify/opportify-sdk-php

Quick start: validating a single email

use Opportify\Sdk\EmailInsights;

$emailInsights = new EmailInsights("YOUR-API-KEY-HERE");

$params = [
    "email" => "user@gmial.com", // typo example for autocorrection
    "enableAi" => true,
    "enableAutoCorrection" => true
];

try {
    $result = $emailInsights->analyze($params);
    print_r([
        "isDeliverable"    => $result->isDeliverable ?? null,  // "yes" | "no" | "unknown"
        "isCatchAll"       => $result->isCatchAll ?? null,
        "isMailboxFull"    => $result->isMailboxFull ?? null,
        "isReachable"      => $result->isReachable ?? null,
        "normalizedScore"  => $result->normalizedScore ?? null,
        "riskLevel"        => $result->riskLevel ?? ($result->riskReport->level ?? null),
        "provider"         => $result->provider ?? null,
        "domain"           => $result->domain ?? null
    ]);
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

When to enable AI and autocorrection

  • enableAutoCorrection=true helps correct user typos at signup or in forms.
  • enableAi=true enriches analysis with domain intelligence, MX and DNS integrity, and risk scoring.

Batch analysis

Use batch operations to process multiple emails at once. Jobs are queued asynchronously and return a jobId you can use to check status.

1. Batch email analysis (JSON)

use Opportify\Sdk\EmailInsights;

$emailInsights = new EmailInsights("YOUR-API-KEY-HERE");

$params = [
    "emails" => [
        "user1@company.com",
        "user2@domain.org"
    ],
    "name" => "Customer Email Validation",
    "enableAi" => true,
    "enableAutoCorrection" => true
];

$batch = $emailInsights->batchAnalyze($params);
$status = $emailInsights->getBatchStatus($batch->jobId);

2. Batch email analysis (plain text)

$content = "one@example.com\nTwo.User@example.org";
$batch = $emailInsights->batchAnalyze(["text" => $content], "text/plain");
$status = $emailInsights->getBatchStatus($batch->jobId);

3. Batch email analysis (file upload)

$batch = $emailInsights->batchAnalyzeFile(__DIR__ . '/emails.csv', [
    "name" => "Monthly Cleanup",
    "enableAi" => true,
    "enableAutoCorrection" => true
]);

$status = $emailInsights->getBatchStatus($batch->jobId);

Tips for batches

  • Split uploads into smaller jobs for faster completion and easier retries.
  • Persist the jobId in your database to track results even if a process restarts.
  • Poll status at short intervals and back off gradually to reduce API load.

Handling errors safely

Always wrap API calls in a try-catch block to handle exceptions cleanly.

use OpenAPI\Client\ApiException;

try {
    $result = $emailInsights->analyze($params);
} catch (ApiException $e) {
    error_log("API error: " . $e->getResponseBody());
    throw new \Exception("Request failed: " . $e->getMessage());
}
Function Type Example
$e->getMessage() string [403] Client error: POST ... 403 Forbidden
$e->getResponseBody() string {"errorMessage":"Your plan does not support AI features"}
$e->getCode() integer 403

Enabling debug mode

For local troubleshooting:

$emailInsights->setDebugMode(true);

Avoid enabling this in production environments.

Security and configuration best practices

  • Store your OPPORTIFY_API_KEY securely using your organization’s secret management method. How it is loaded or accessed in your environment is up to your security policy.
  • Never commit the API key to version control or expose it in logs.
  • Avoid printing raw API payloads that include personal or sensitive information.

Access control Email Insights supports API Key Access Control Lists (ACLs), allowing you to restrict API key usage to specific IP addresses or ranges. Configure allow-listed rules in your account settings so only approved systems can call the API.

Interpreting results

Deliverability is tri-state isDeliverable returns yes, no, or unknown. Use isMailboxFull, isCatchAll, and isReachable to refine decisions.

Risk scoring normalizedScore ranges from 200 to 1000 and maps to fixed risk levels:

Risk Level Score Range Action
Lowest ≤ 300 Accept - safe to include in campaigns
Low 300-400 Monitor and include
Medium 400-600 Revalidate or route to secondary flow
High 600-800 Exclude from primary campaigns
Highest > 800 Reject or review for potential fraud

Decision helper (tri-state aware)

function classify_contact(array $result): string {
    $deliverable   = strtolower($result['isDeliverable'] ?? '');
    $riskLevel     = strtolower($result['riskLevel'] ?? ($result['riskReport']['level'] ?? ''));
    $isCatchAll    = (bool)($result['isCatchAll'] ?? false);
    $isMailboxFull = (bool)($result['isMailboxFull'] ?? false);
    $isReachable   = (bool)($result['isReachable'] ?? false);
    $signals       = $result['signals'] ?? [];
    $isDisposable  = (bool)($signals['isDisposableDomain'] ?? false);

    if ($isDisposable || $riskLevel === 'highest') {
        return 'reject';
    }
    if ($deliverable === 'no') {
        return $isMailboxFull ? 'revalidate' : 'reject';
    }
    if ($deliverable === 'unknown') {
        if ($riskLevel === 'high') return 'review';
        if ($isCatchAll || !$isReachable) return 'revalidate';
        return 'review';
    }
    // deliverable === 'yes'
    if ($riskLevel === 'high') return 'review';
    if ($riskLevel === 'medium' || $isCatchAll) return 'revalidate';
    return 'accept';
}

Where to go next

Reference: SDK entry points

  • EmailInsights->analyze($params)
  • EmailInsights->batchAnalyze($params)
  • EmailInsights->batchAnalyzeFile($path, $params)
  • EmailInsights->getBatchStatus($jobId)
  • EmailInsights->setDebugMode(true)