SDK QUICKSTART

Verify emails from Node.js & TypeScript.

ESM + CJS, generated from the OpenAPI spec, full types out of the box.

1. Install

Grab a free API key at tooltrace.io/signup. The free plan includes 1,000 verifications per month.

Installbash
npm install @tooltrace/sdk

2. Quickstart

Set TOOLTRACE_KEY in your environment, then verify a single address.

Verify a single addresstypescript
import { ToolTrace } from "@tooltrace/sdk";

const client = new ToolTrace({ apiKey: process.env.TOOLTRACE_KEY! });

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

console.log(result.status);     // 'valid'
console.log(result.score);      // 97
console.log(result.checks.mx);  // true

if (result.status === "valid" && result.score >= 80) {
  await acceptLead(result.email);
} else {
  await flagForReview(result);
}

3. Bulk verify

Submit up to 50,000 addresses in one job. Duplicates on the normalised form are deduped server-side and never charged. A signed webhook fires on completion.

Bulk verify a CSVtypescript
const job = await client.bulkVerify({
  emails: await loadCsv("leads.csv"),      // up to 50,000 addresses
  webhookUrl: "https://your.app/hooks/tooltrace",
});

console.log(job.jobId);                     // 'job_01HM8K2TGQX5RTF9W6'
console.log(job.uniqueCount);               // dedupe-free billing
console.log(job.estimatedCredits);

// Your webhook fires on completion; verify the HMAC signature:
import { verifyWebhookSignature } from "@tooltrace/sdk/webhook";

app.post("/hooks/tooltrace", async (req, res) => {
  const valid = verifyWebhookSignature(
    req.rawBody,
    req.headers["x-tooltrace-signature"] as string,
    process.env.TOOLTRACE_WEBHOOK_SECRET!,
  );
  if (!valid) return res.status(401).send();
  for await (const row of client.jobResults(req.body.jobId)) {
    await writeRow(row);
  }
  res.send("ok");
});

4. Advanced

Patterns for production use: idempotency, retries, and typed errors.

Idempotency and retriestypescript
const client = new ToolTrace({
  apiKey: process.env.TOOLTRACE_KEY!,
  maxRetries: 3,              // Retry-After honoured automatically
  timeout: 15_000,
});

// Idempotency-Key: safe to retry the same request within 24h.
const result = await client.verifyEmail(
  { email: "[email protected]" },
  { idempotencyKey: requestId },
);

// Catch typed errors
import { RateLimitError, InvalidKeyError } from "@tooltrace/sdk";

try {
  await client.verifyEmail({ email: input });
} catch (e) {
  if (e instanceof RateLimitError) await sleep(e.retryAfter * 1000);
  else if (e instanceof InvalidKeyError) rotateKey();
  else throw e;
}

What you get

  • Full TypeScript types generated from the OpenAPI spec
  • ESM + CJS dual package, works in Node 18+, Bun, Deno
  • Idempotency keys + signed webhook verification helper included
  • Automatic Retry-After handling on 429
  • Zero runtime dependencies except @types for TS projects

External links