Spamuraiz SDK

Official Node.js SDK for the Spamuraiz email validation service.

Visit https://tempmailblocker.com/ to purchase credits and get started.

Installation

npm install spamuraiz-sdk

Quick Start

const { Spamuraiz } = require('spamuraiz-sdk');

// Initialize the SDK
const spamuraiz = new Spamuraiz({
  apiKey: "your-api-key",
  baseUrl: "https://tempmailblocker.com"
});

// Validate a single email
async function validateEmail() {
  try {
    const result = await spamuraiz.singleValidation({
      email: "[email protected]"
    });
    console.log(result);
  } catch (error) {
    console.error('Validation failed:', error.message);
  }
}

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import { Spamuraiz, SingleValidationResponse } from 'spamuraiz-sdk';

const spamuraiz = new Spamuraiz({
  apiKey: "your-api-key",
  baseUrl: "https://tempmailblocker.com"
});

const result: SingleValidationResponse = await spamuraiz.singleValidation({
  email: "[email protected]"
});

API Reference

Constructor

new Spamuraiz(config: SpamuraizConfig)

Parameters:

• config.apiKey (string): Your Spamuraiz API key
• config.baseUrl (string): The base URL of the Spamuraiz API

Single Email Validation

singleValidation(request: SingleValidationRequest): Promise<SingleValidationResponse>

Validates a single email address and returns detailed validation results.

Example:

const result = await spamuraiz.singleValidation({
  email: "[email protected]"
});

console.log(result);
// {
//   email: "[email protected]",
//   valid: true,
//   score: 95,
//   details: {
//     syntax: true,
//     domain: true,
//     mx: true,
//     disposable: false,
//     role: false,
//     free: false
//   }
// }

Bulk Email Validation

Create Bulk Job

createBulkJob(request: BulkValidationRequest): Promise<BulkValidationJob>

Creates a bulk validation job for multiple emails.

Example:

const job = await spamuraiz.createBulkJob({
  emails: [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ],
  name: "My Email List" // optional
});

console.log(job.jobId); // Use this to check status and get results

Check Job Status

getJobStatus(jobId: string): Promise<BulkValidationJob>

Example:

const status = await spamuraiz.getJobStatus(job.jobId);
console.log(status.status); // 'pending', 'processing', 'completed', or 'failed'
console.log(`${status.processedEmails}/${status.totalEmails} processed`);

Get Job Results

getJobResults(jobId: string): Promise<BulkValidationResult>

Example:

// Only call this when job status is 'completed'
const results = await spamuraiz.getJobResults(job.jobId);

console.log(results.summary);
// {
//   total: 3,
//   valid: 2,
//   invalid: 1,
//   processed: 3
// }

results.results.forEach(result => {
  console.log(`${result.email}: ${result.valid ? 'Valid' : 'Invalid'}`);
});

Wait for Job Completion

waitForJobCompletion(jobId: string, pollIntervalMs?: number, timeoutMs?: number): Promise<BulkValidationResult>

Convenience method that polls for job completion and returns results automatically.

Example:

// Create job and wait for completion
const job = await spamuraiz.createBulkJob({
  emails: ["[email protected]", "[email protected]"]
});

try {
  const results = await spamuraiz.waitForJobCompletion(
    job.jobId,
    5000,  // Poll every 5 seconds
    300000 // Timeout after 5 minutes
  );

  console.log('Job completed:', results.summary);
} catch (error) {
  console.error('Job failed or timed out:', error.message);
}

Job Management

List Jobs

listJobs(limit?: number, offset?: number): Promise<BulkValidationJob[]>

Example:

const jobs = await spamuraiz.listJobs(10, 0); // Get first 10 jobs
jobs.forEach(job => {
  console.log(`Job ${job.jobId}: ${job.status}`);
});

Delete Job

deleteJob(jobId: string): Promise<void>

Example:

await spamuraiz.deleteJob(job.jobId);
console.log('Job deleted successfully');

Error Handling

The SDK throws descriptive errors that you can catch and handle:

try {
  const result = await spamuraiz.singleValidation({
    email: "invalid-email"
  });
} catch (error) {
  if (error.statusCode) {
    // API error
    console.error(`API Error ${error.statusCode}: ${error.message}`);
    console.error('Error Code:', error.code);
  } else {
    // Network or other error
    console.error('Error:', error.message);
  }
}

Response Types

SingleValidationResponse

interface SingleValidationResponse {
  email: string;
  valid: boolean;
  score: number;          // 0-100 validation score
  reason?: string;        // Reason if invalid
  details?: {
    syntax: boolean;      // Email syntax is valid
    domain: boolean;      // Domain exists
    mx: boolean;          // MX record exists
    disposable: boolean;  // Is disposable email
    role: boolean;        // Is role-based email
    free: boolean;        // Is free email provider
  };
}

BulkValidationJob

interface BulkValidationJob {
  jobId: string;
  status: 'pending' | 'processing' | 'completed' | 'failed';
  totalEmails: number;
  processedEmails: number;
  createdAt: string;
  completedAt?: string;
}

BulkValidationResult

interface BulkValidationResult {
  jobId: string;
  status: 'pending' | 'processing' | 'completed' | 'failed';
  results: SingleValidationResponse[];
  summary: {
    total: number;
    valid: number;
    invalid: number;
    processed: number;
  };
}

Complete Example

const { Spamuraiz } = require('spamuraiz-sdk');

async function main() {
  const spamuraiz = new Spamuraiz({
    apiKey: process.env.SPAMURAIZ_API_KEY,
    baseUrl: "https://tempmailblocker.com"
  });

  try {
    // Single validation
    console.log('=== Single Validation ===');
    const singleResult = await spamuraiz.singleValidation({
      email: "[email protected]"
    });
    console.log('Single validation result:', singleResult);

    // Bulk validation
    console.log('\n=== Bulk Validation ===');
    const bulkJob = await spamuraiz.createBulkJob({
      emails: [
        "[email protected]",
        "[email protected]",
        "invalid@email"
      ],
      name: "Test Validation"
    });

    console.log('Bulk job created:', bulkJob.jobId);

    // Wait for completion
    const bulkResults = await spamuraiz.waitForJobCompletion(bulkJob.jobId);
    console.log('Bulk validation completed:', bulkResults.summary);

    // Print individual results
    bulkResults.results.forEach(result => {
      console.log(`${result.email}: ${result.valid ? '✓' : '✗'} (Score: ${result.score})`);
    });

  } catch (error) {
    console.error('Error:', error.message);
  }
}

main();

License

MIT

Support

For questions and support, please visit our documentation or contact [email protected].