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.
npm install @tooltrace/sdk 2. Quickstart
Set TOOLTRACE_KEY in your environment, then verify a single address.
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.
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.
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