apiddress

Official Node.js SDK for the APIddress email validation API.

• Zero runtime dependencies (built on global fetch)
• Node 18+, ESM, full TypeScript types
• Automatic retry with backoff on 429 and 5xx (batch creation is never retried)

Install

npm install @apiddress/sdk

Quickstart

import { APIddress } from "@apiddress/sdk";

const client = new APIddress("YOUR_API_KEY");

const result = await client.validateEmail("[email protected]");
console.log(result.status); // "valid"
console.log(result.score);  // 0.98

Configuration

const client = new APIddress("YOUR_API_KEY", {
  baseUrl: "https://api.apiddress.com", // default
  timeoutMs: 10_000,                    // per-request timeout, default 10s
  maxRetries: 2,                        // retries on 429/5xx, default 2
});

Usage

Validate one email

const result = await client.validateEmail("[email protected]", {
  check_smtp: false,       // default
  allow_role_based: true,  // default
});
// result.status: "valid" | "invalid" | "risky" | "disposable" | "unknown"
// result.suggestion: "[email protected]" for typo-like addresses, else null
// result.checks: { syntax, domain_exists, mx, smtp, disposable, ... }

A malformed value (e.g. "not-an-email") is a verdict, not an error: you get status: "invalid" with reason: "invalid_syntax".

Validate up to 100 emails synchronously

const { count, results } = await client.validateEmails([
  "[email protected]",
  "[email protected]",
]);

Batch jobs (up to 5000 emails)

const batch = await client.createBatch(emails, {
  callback_url: "https://yourapp.com/webhooks/apiddress", // optional
});

const done = await client.waitForBatch(batch.batch_id, {
  pollMs: 1_000,     // default
  timeoutMs: 60_000, // default
});
console.log(done.status, done.results.length);

// Or poll yourself:
const status = await client.getBatch(batch.batch_id);

waitForBatch resolves with the terminal state ("completed" or "failed") — check status before using results.

Account

const profile = await client.me();        // plan, limits, usage
const usage = await client.usage();       // current month
const may = await client.usage("2026-05"); // specific month
const health = await client.health();     // no auth required

Error handling

Every failed request throws an APIddressError:

import { APIddress, APIddressError } from "@apiddress/sdk";

try {
  await client.validateEmail("[email protected]");
} catch (err) {
  if (err instanceof APIddressError) {
    console.error(err.status, err.code, err.message, err.details);
    // 429 quota_exceeded "Monthly request limit exceeded." { requests_used: ..., requests_limit: ... }
  }
}

| status | code | | -------- | ------------------ | | 400 | invalid_request | | 401 | unauthorized | | 404 | not_found | | 429 | quota_exceeded | | 500 | internal_error | | 0 | timeout (request or waitForBatch timeout) |

Development

npm install
npm run build   # tsc -> dist/ (ESM + .d.ts)

# Integration tests need a live backend:
APIDDRESS_BASE_URL=http://localhost:3000 APIDDRESS_API_KEY=test_key_local_dev npm test

License

MIT