# JavaScript / Node.js

Check emails with the IronDome Node.js client. Reuse its HTTPS pool, classify API errors, and submit bulk checks.

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:

```sh
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`.

```js
// 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:

```js
// 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.

```js
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](/docs/api/bulk) and [performance guide](/docs/guides/performance).