Getting Started with PHP

Safe API Key Storage

In a production setup, do not store API Keys in the host's environment variables or in the source code.

Requirements

Requires PHP v8.1 or later.

Getting Started

First, install Opportify via the Composer package manager:

composer require opportify/opportify-sdk-php

Calling Email Insights

use Opportify\Sdk\EmailInsights;

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

$params = [
    "email" => "test@gmial.com", // *gmial* - just an example to be auto-corrected
    "enableAi" => true,
    "enableAutoCorrection" => true,
    "enableDomainEnrichment" => true // optional
];

$result = $emailInsights->analyze($params);

Calling IP Insights

use Opportify\Sdk\IpInsights;

$ipInsights = new IpInsights("<YOUR-KEY-HERE>");

$params = [
    "ip" => "3.1.122.82",
    "enableAi" => true
];

$result = $ipInsights->analyze($params);

Calling Fraud Protection

use Opportify\Sdk\FraudProtection;

$fraudProtection = new FraudProtection("<YOUR-KEY-HERE>");

$result = $fraudProtection->analyze([
    // Identity
    "email" => "user@example.com",
    "firstName" => "Jane",
    "lastName" => "Doe",
    "username" => "jane_doe",
    "companyName" => "Acme Corp",

    // Network
    "userIp" => "3.1.122.82",

    // Contact details
    "phone1" => "+1-800-555-0100",
    "website" => "https://acme.example.com",

    // Submission context
    "subject" => "Contact form submission",
    "message" => "Hello, I am interested in your service.",
    "submissionType" => "contact", // e.g., "contact", "signup", "checkout"
    "origin" => "yoursite.com", // hostname only

    // Address (all optional)
    "address1" => "123 Main St",
    "city" => "Springfield",
    "region" => "IL",
    "country" => "US",
    "postalCode" => "62701",

    // Token & form tracking (optional)
    "opportifyToken" => "opportify-generated-token",
    "opportifyFormUUID" => "uuid-of-the-form",

    // Raw form fields (optional)
    "formData" => ["custom_field" => "value"],
]);

// $result->score   — integer 200-1000 (higher = riskier)
// $result->level   — "lowest" | "low" | "medium" | "high" | "highest"
// $result->factors — string[] of detected risk signals
// $result->sources — per-signal breakdown (email, IP, geo, session, velocity)

Batch Analysis (Email & IP)

You can submit multiple emails or IPs in a single request. Batch jobs are processed asynchronously; the response returns a job identifier (jobId) you can poll for status.

1. Batch Email Analysis (JSON)

use Opportify\Sdk\EmailInsights;

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

$params = [
    'emails' => [
        'one@example.com',
        'two@example.org'
    ],
    'name' => 'Customer Email Validation', // Optional: descriptive name for the job
    'enableAi' => true,
    'enableAutoCorrection' => true
];

// Default content type is application/json
$batch = $emailInsights->batchAnalyze($params);

// Optional: poll status later
$status = $emailInsights->getBatchStatus($batch->jobId);

2. Batch Email Analysis (Plain Text)

Provide one email per line and set the content type to text/plain.

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

3. Batch Email Analysis (File Upload)

Supply a .csv (one email per row; header optional) via batchAnalyzeFile(). A .csv triggers multipart/form-data; other extensions fall back to text/plain (newline-delimited body).

$batch = $emailInsights->batchAnalyzeFile(__DIR__.'/emails.csv', [
    'name' => 'Monthly Email Cleanup', // Optional: descriptive name for the job
    'enableAi' => true,
    'enableAutoCorrection' => true
]);
$status = $emailInsights->getBatchStatus($batch->jobId);

4. Batch IP Analysis (JSON)

use Opportify\Sdk\IpInsights;

$ipInsights = new IpInsights("<YOUR-KEY-HERE>");

$params = [
    'ips' => [
        '1.1.1.1',
        '8.8.8.8'
    ],
    'name' => 'Network Security Scan', // Optional: descriptive name for the job
    'enableAi' => true
];

$batch = $ipInsights->batchAnalyze($params); // application/json
$status = $ipInsights->getBatchStatus($batch->jobId);

5. Batch IP Analysis (Plain Text)

$content = "1.1.1.1\n8.8.8.8"; // newline-delimited IPs
$batch = $ipInsights->batchAnalyze(['text' => $content], 'text/plain');
$status = $ipInsights->getBatchStatus($batch->jobId);

6. Batch IP Analysis (File Upload)

$batch = $ipInsights->batchAnalyzeFile(__DIR__.'/ips.csv', [
    'name' => 'Firewall IP Assessment', // Optional: descriptive name for the job
    'enableAi' => true
]);
$status = $ipInsights->getBatchStatus($batch->jobId);

Convenience & Notes

• batchAnalyzeFile() auto-selects content type: .csv -> multipart/form-data; otherwise text/plain.
• For text/plain, pass newline-delimited values via the text key.
• For multipart/form-data, pass a readable file path via the file key (handled internally by batchAnalyzeFile()).
• The name parameter is optional for all batch operations and helps with job identification and tracking.
• enableAutoCorrection applies only to Email Insights.
• Always wrap calls in a try-catch (see Error Handling) to capture API errors.
• Polling cadence depends on payload size; a short delay (1-3s) between status checks is recommended.

Batch Exports

Once a batch job completes, you can create filtered exports in CSV or JSON format.

Email Batch Export

$export = $emailInsights->createBatchExport($batch->jobId, [
    'exportType' => 'csv', // or 'json'
    'columns' => [
        'emailAddress',
        'emailProvider',
        'riskReport.score',
        'isDeliverable',
    ],
    'filters' => [
        'isDeliverable' => 'yes',
        'riskReport.score' => ['min' => 400],
    ],
]);

// Poll for export status
$exportStatus = $emailInsights->getBatchExportStatus($batch->jobId, $export->exportId);
// $exportStatus->status — "QUEUED" | "PROCESSING" | "COMPLETED" | "FAILED"
// $exportStatus->downloadUrl — available when status === "COMPLETED"

IP Batch Export

$export = $ipInsights->createBatchExport($batch->jobId, [
    'exportType' => 'json', // or 'csv'
    'columns' => [
        'result.ipAddress',
        'result.connectionType',
        'result.riskReport.score',
    ],
    'filters' => [
        'result.riskReport.level' => ['low', 'medium'],
    ],
]);

// Poll for export status
$exportStatus = $ipInsights->getBatchExportStatus($batch->jobId, $export->exportId);
// $exportStatus->status — "QUEUED" | "PROCESSING" | "COMPLETED" | "FAILED"

Enabling Debug Mode

$emailInsights->setDebugMode(true);

Handling Errors

We strongly recommend that any usage of this SDK happens within a try-catch to properly handle any exceptions or errors.

use OpenAPI\Client\ApiException;

try {

    // Email or IP Insights usage...

} catch (ApiException $e) {
    throw new \Exception($e->getResponseBody());
}

For Fraud Protection, use the dedicated exception namespace:

use OpenAPI\FraudIntel\Client\ApiException;

try {

    // Fraud Protection usage...

} catch (ApiException $e) {
    throw new \Exception($e->getResponseBody());
}

Below are the ApiException functions available:

Function	Type	Value Sample
$e->getMessage();	string	"[403] Client error: POST https://api.opportify.ai/insights/v1/... resulted in a 403 Forbidden"
$e->getResponseBody();	string	"{"errorMessage":"Your plan does not support AI features, please upgrade your plan or set enableAI as false.","errorCode":"INVALID_PLAN"}"
$e->getCode();	integer	403