JavaScript / Node.js

Check a signup address from your Node.js server before creating an account. Keep the API key in server configuration and reuse one client across requests.

Availability

Install the published JavaScript SDK:

npm install @irondome-dev/sdk@0.2.0

Use Node.js 22 or newer.

Create and reuse a client

Set IRONDOME_API_KEY in your server environment. The SDK defaults to https://api.irondome.dev.

// server.mjs
import { IronDome, APIError } from '@irondome-dev/sdk/node';

const client = new IronDome({
  apiKey: process.env.IRONDOME_API_KEY,
  timeoutMs: 5000,
});

export async function checkEmail(email) {
  try {
    return await client.check(email);
  } catch (error) {
    if (error instanceof APIError) {
      console.error({ status: error.status, code: error.code, requestId: error.requestId });
    }
    throw error;
  }
}

// Call this from the server's shutdown hook, after requests have drained.
export function closeIronDome() {
  client.close();
}

For a one-shot script, close its client after the check completes:

// check-once.mjs
import { checkEmail, closeIronDome } from './server.mjs';

try {
  console.log(await checkEmail('person@example.com'));
} finally {
  closeIronDome();
}

Call checkEmail from your existing signup flow. Do not expose an unrestricted public endpoint that forwards arbitrary checks. The client owns a keep-alive HTTPS pool; closing it after each request discards that pool and can interrupt concurrent calls.

Results and failures

check() returns provider, valid, disposable, and reason, with optional requestId and detectorVersion. A disposable result can guide your signup policy. valid does not prove that a mailbox exists or can receive mail.

An invalid address is an APIError with status 422 and code invalid_email. Configuration, local validation, busy-client, timeout, protocol, and transport failures are also errors. Do not convert a failure to disposable: false; a timed-out request may already have been processed.

Warmup and bulk checks

client.warmup() optionally sends an unauthenticated health request through the same pool. Start it ahead of independent work if useful; avoid adding a health round trip before every check.

const batch = await client.checkBulk(['person@example.com', 'invalid']);
for (const item of batch.results) {
  if ('error' in item) console.log(item.index, item.error.code);
  else console.log(item.index, item.disposable);
}

Bulk results preserve input order. Each syntactically valid address counts as a check. See the bulk API guide and performance guide.