A typed client and Express middleware for Node and TypeScript.
Install from npm. The package ships ESM and CommonJS builds with full TypeScript types, and uses the native fetch — no extra HTTP dependency.
npm install @bounceshift/sdkCreate a client with your API key and organization ID (your team ID), then await validate(). The result is fully typed:
import { BounceShift, isSafeToSend } from '@bounceshift/sdk';
const bounceshift = new BounceShift({
apiKey: process.env.BOUNCESHIFT_API_KEY!,
organizationId: process.env.BOUNCESHIFT_ORGANIZATION_ID!,
});
const result = await bounceshift.validate('[email protected]');
result.status; // 'valid' | 'catch_all' | 'unknown' | 'invalid' | ...
result.confidence; // 0-100
isSafeToSend(result); // true for 'valid' or 'catch_all'
result.smtpValid; // boolean | null
result.fromCache; // boolean — no credit is spent on a cache hitThe reason to reach for this package in a web app: a drop-in deliverableEmail middleware that stops undeliverable addresses at your signup or checkout route.
import { deliverableEmail } from '@bounceshift/sdk';
// Lenient by default: blocks only decisively-bad addresses, passes "unknown",
// and fails open if the API is unreachable — so it never blocks real users.
app.post('/signup', deliverableEmail({ client: bounceshift }), (req, res) => {
// reached only when the email field is deliverable
});
// Opt in to stricter policies when your "unknown" rate is low:
deliverableEmail({ client: bounceshift, strict: true }); // also blocks risky/unknown
deliverableEmail({ client: bounceshift, minConfidence: 70 }); // confidence floorIt is lenient by default, on purpose. It blocks only decisively-bad results (invalid, disposable, do_not_mail, abuse, spamtrap), passes unknown/risky/catch_all, and fails open if the API is unreachable — so a probe that can't reach a mailbox (or an outage) never blocks a real person. Turn on strict or minConfidence only when you know your unknown rate is low.
Non-success responses reject with typed errors. See the status & error codes reference for the full mapping.
import { InsufficientCreditsError, RateLimitError, BounceShiftError } from '@bounceshift/sdk';
try {
const result = await bounceshift.validate(email);
} catch (err) {
if (err instanceof InsufficientCreditsError) { /* 402 */ }
else if (err instanceof RateLimitError) { /* 429 — err.retryAfter */ }
else if (err instanceof BounceShiftError) { /* network/timeout/other */ }
}Related terms
Get 100 free validations to test our service. No credit card required.
Start Free Trial