Getting Started with Node.js

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

Recommended Node version 22.x.x. It is also compatible with v20+.

Getting Started

First, install Opportify via the npm package manager:

npm install --save @opportify/sdk-nodejs

Calling Email Insights

import { EmailInsights } from '@opportify/sdk-nodejs';
import type { ErrorResponse } from '@opportify/sdk-nodejs';

const emailInsights = new EmailInsights({
  apiKey: 'YOUR-API-KEY-HERE'
});

async function analyzeEmail() {
  try {
    const response = await emailInsights.analyze({
      email: "email_to_validate@domain.com",
      enableAutoCorrection: true,
      enableAI: true, // only available on paid plans.
      enableDomainEnrichment: true, // optional
    });
    console.log('response', response);
  } catch (error: unknown) {
    const err = error as ErrorResponse;
    console.error(`[${err.errorCode}] ${err.errorMessage}`);
  }
}

analyzeEmail();

Calling IP Insights

import { IPInsights } from '@opportify/sdk-nodejs';
import type { ErrorResponse } from '@opportify/sdk-nodejs';

const ipInsights = new IPInsights({
  apiKey: 'YOUR-API-KEY-HERE'
});

async function analyzeIP() {
  try {
    const response = await ipInsights.analyze({
      ip: '8.8.8.8',
      enableAI: true // only available on paid plans.
    });
    console.log('response', response);
  } catch (error: unknown) {
    const err = error as ErrorResponse;
    console.error(`[${err.errorCode}] ${err.errorMessage}`);
  }
}

analyzeIP();

Calling Fraud Protection

import { FraudProtection } from '@opportify/sdk-nodejs';
import type { ErrorResponse } from '@opportify/sdk-nodejs';

const fraudProtection = new FraudProtection({
  apiKey: 'YOUR-API-KEY-HERE'
});

async function analyzeFraud() {
  try {
    const response = await fraudProtection.analyzeFraud({
      // Identity
      email: 'user@example.com',
      firstName: 'Jane',
      lastName: 'Doe',
      username: 'jane_doe',
      companyName: 'Acme Corp',

      // Network
      userIp: '3.1.122.82',

      // Contact details
      phone1: '+18005550100',
      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 as key-value pairs (optional)
      formData: { custom_field: 'value' },
    });

    // response.score   — integer 200-1000 (higher = riskier)
    // response.level   — "lowest" | "low" | "medium" | "high" | "highest"
    // response.factors — string[] of detected risk signals
    // response.sources — per-signal breakdown (email, IP, geo, session, velocity)
    console.log('response', response);
  } catch (error: unknown) {
    const err = error as ErrorResponse;
    console.error(`[${err.errorCode}] ${err.errorMessage}`);
  }
}

analyzeFraud();

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.

Batch Email Analysis

import { EmailInsights } from '@opportify/sdk-nodejs';

const emailInsights = new EmailInsights({ apiKey: 'YOUR-API-KEY-HERE' });

async function batchAnalyzeEmails() {
  const batchResponse = await emailInsights.batchAnalyze({
    emails: ['one@example.com', 'two@example.org'],
    name: 'Customer Email Validation', // optional
    enableAI: true,
    enableAutoCorrection: true,
  });

  const jobId = batchResponse.jobId;

  // Poll for status
  const statusResponse = await emailInsights.getBatchStatus({ jobId });
  // statusResponse.status — "QUEUED" | "PROCESSING" | "COMPLETED" | "ERROR"
}

batchAnalyzeEmails();

Batch IP Analysis

import { IPInsights } from '@opportify/sdk-nodejs';

const ipInsights = new IPInsights({ apiKey: 'YOUR-API-KEY-HERE' });

async function batchAnalyzeIPs() {
  const batchResponse = await ipInsights.batchAnalyze({
    ips: ['8.8.8.8', '1.1.1.1', '203.0.113.1'],
    name: 'Network Security Audit', // optional
    enableAI: true,
  });

  const jobId = batchResponse.jobId;

  // Poll for status
  const statusResponse = await ipInsights.getBatchStatus({ jobId });
  // statusResponse.status — "QUEUED" | "PROCESSING" | "COMPLETED" | "ERROR"
}

batchAnalyzeIPs();

Batch Exports

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

Email Batch Export

const exportResponse = await emailInsights.createEmailBatchExport({
  jobId,
  exportRequest: {
    exportType: 'csv', // or 'json'
    columns: [
      'emailAddress',
      'emailProvider',
      'riskReport.score',
      'isDeliverable',
    ],
    filters: {
      isDeliverable: 'yes',
      'riskReport.score': { min: 400 },
    },
  },
});

const exportId = exportResponse.exportId;

// Poll for export status
const exportStatus = await emailInsights.getEmailBatchExportStatus({ jobId, exportId });
// exportStatus.status — "QUEUED" | "PROCESSING" | "COMPLETED" | "FAILED"
// exportStatus.downloadUrl — available when status === "COMPLETED"

IP Batch Export

const exportResponse = await ipInsights.createIpBatchExport({
  jobId,
  exportRequest: {
    exportType: 'json', // or 'csv'
    columns: [
      'result.ipAddress',
      'result.connectionType',
      'result.riskReport.score',
    ],
    filters: {
      'result.riskReport.level': ['low', 'medium'],
    },
  },
});

const exportId = exportResponse.exportId;

// Poll for export status
const exportStatus = await ipInsights.getIpBatchExportStatus({ jobId, exportId });
// exportStatus.status — "QUEUED" | "PROCESSING" | "COMPLETED" | "FAILED"

Handling Errors

We strongly recommend wrapping all SDK calls in a try-catch block. The SDK provides a normalized ErrorResponse type.

import type { ErrorResponse } from '@opportify/sdk-nodejs';

try {
  const result = await emailInsights.analyze({ email: 'test@example.com' });
} catch (error: unknown) {
  const err = error as ErrorResponse;
  // err.errorCode    — e.g., "HTTP_403", "HTTP_429", "REQUEST_ERROR"
  // err.errorMessage — human-readable description
  console.error(`[${err.errorCode}] ${err.errorMessage}`);
}

Error Code	Description
HTTP_403	Insufficient permissions (e.g., plan doesn't support AI)
HTTP_429	Rate limit exceeded
REQUEST_ERROR	Network or general request failure
UNKNOWN_ERROR	Unclassified error