@bye_bouncer/sdk
v0.4.0
Published
Official Node.js SDK for the ByeBouncer email, phone and IP data validation API.
Maintainers
Readme
@bye_bouncer/sdk
Official Node.js/TypeScript SDK for the ByeBouncer data validation API.
Email, IP and phone verification, email-only bulk jobs (up to 5,000 unique emails per job), CSV downloads and HMAC-signed webhooks.
Billable cache hits cost the same as fresh results: email 1 credit, public IP 1, valid local phone 1 or conclusive carrier-enriched phone 3. Before the first purchase, phone checks also use a shared 30-credit starter quota.
Install
npm install @bye_bouncer/sdk
# or
pnpm add @bye_bouncer/sdk
# or
yarn add @bye_bouncer/sdkRequires Node.js 18+.
The default API URL is https://api.byebouncer.com; each user supplies their own
secret API key from the dashboard. Keep keys in environment variables on your server.
To upgrade an existing installation, run npm install @bye_bouncer/sdk@latest.
Independent validation services (0.4.0)
Choose an explicit service to control the information returned and its cost. The 0.4.0 methods use the factual validation-v1 contract: independent checks and attributes without scores or a contact acceptance decision. Existing methods and routes remain available for compatibility.
import { ByeBouncer } from "@bye_bouncer/sdk";
const client = new ByeBouncer({ apiKey: process.env.BB_API_KEY! });
const result = await client.validate({ email: "[email protected]", phone: "+12025550123", phone_mode: "local", live: false });
console.log(result.results.email?.deliverability);
console.log(result.results.phone?.checks);
// One service at a time (0.4.0+):
await client.validateEmail("[email protected]"); // POST /verify-email · 1 credit
await client.lookupIP("8.8.8.8"); // POST /verify-ip · 1 credit
await client.validatePhoneLocal("+12025550123"); // POST /verify-phone/local · 1 credit
await client.lookupPhoneCarrier("+12025550123"); // POST /verify-phone/carrier · 3 credits
await client.lookupPhoneNetwork("+12025550123"); // POST /verify-phone/live · 6 credits
// In client.validate(...), set phone_mode: "local" | "carrier" to choose the phone service.
// Factual email CSV: client.bulk({ emails, result_format: "validation-v1" }).Examples are illustrative. completed describes execution, not a favorable finding. unavailable does not mean invalid. Domain attributes, number format and network observations do not establish identity, ownership or commercial intent. Mobile network lookup is optional and has its own cost; it does not prove someone will answer.
Existing methods below keep the legacy contract for compatibility. Do not interpret legacy scores as fraud probabilities.
Three phone validation levels
| Level | Information | Credits per billable request | |---|---|---:| | 1 · Local | Numbering-plan format, normalization, country and estimated type; no remote provider call | 1 | | 2 · Carrier | Format validation and available carrier data; no extra format charge | 3 total | | 3 · Mobile network | Last network observation and timestamp; no call or message sent | 6 |
The levels are independent. Network status needs no prior carrier lookup. Local plus network costs up to 7 credits; carrier plus network, up to 9. A valid format does not prove a live line; network registration does not guarantee an answered call. unknown can be a billable network answer, while provider errors and inapplicable lookups are not charged. Billable cache hits retain the same price.
Legacy quickstart
import { ByeBouncer } from "@bye_bouncer/sdk";
const client = new ByeBouncer({ apiKey: process.env.BB_API_KEY! });
const result = await client.verify("[email protected]");
console.log(result.status); // "deliverable" | "undeliverable" | "risky" | "unknown"
console.log(result.action); // "allow" | "review" | "block"
console.log(result.signals); // ["valid_syntax", "mx_found", ...]
console.log(result.credits_remaining);Get your BB_API_KEY from https://byebouncer.com/dashboard (format bb_live_...).
For CommonJS, use const { ByeBouncer } = require("@bye_bouncer/sdk") in a .cjs
file. JavaScript ESM examples run in .mjs files; the ! assertion in the
TypeScript example above is only needed by TypeScript.
Bulk verification
const { job, estimated_seconds } = await client.bulk({
emails: ["[email protected]", "[email protected]"], // up to 5,000 unique emails
filename: "my_list.csv",
webhook_url: "https://api.myapp.com/hooks/byebouncer", // optional
});
console.log(`Job ${job.id}, ~${estimated_seconds}s`);If you pass webhook_url, the creation response includes the effective
webhook_secret (generated or supplied). Store it immediately; later job reads
never return it.
Polling for completion
For short-running jobs (maximum 5,000 unique emails), poll and download the CSV directly:
import { writeFileSync } from "node:fs";
const { job: final, csv } = await client.bulkAndWait(
{ emails: ["[email protected]", "[email protected]"] },
{
intervalMs: 3000,
timeoutMs: 120_000,
onProgress: (j) => console.log(`${j.processed}/${j.total_emails}`),
}
);
writeFileSync("results.csv", csv);Webhooks (recommended for large jobs)
Prefer webhooks over polling. On completion ByeBouncer POSTs to your URL with:
X-ByeBouncer-Event: bulk.completed
X-ByeBouncer-Signature: <hex HMAC-SHA256(body, webhook_secret)>
Content-Type: application/json
{
"event": "bulk.completed",
"job_id": "...",
"processed": 1234,
"valid": 800, "invalid": 300, "unknown": 134,
"credits_refunded": 0,
"timestamp": "2026-09-05T14:30:00Z"
}Attach or rotate the webhook after creating the job:
const { webhook_secret } = await client.bulkSetWebhook(job.id, {
webhook_url: "https://api.myapp.com/hooks/byebouncer",
});
// Store webhook_secret NOW — it is returned only once.Manual polling + download
Download URLs expire after 15 minutes (900 seconds); request a fresh one when needed. Result CSVs are retained for 7 days after the job reaches a terminal state.
const status = await client.bulkStatus(job.id);
if (status.status === "completed" && status.result_available) {
const { url } = await client.bulkDownloadUrl(job.id);
const res = await fetch(url, { signal: AbortSignal.timeout(30_000) });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const csv = await res.text();
}Cancel
Cancel a pending or processing job; a completed job can no longer be cancelled.
const cancelled = await client.bulkCancel(job.id);
console.log(`Refunded ${cancelled.credits_refunded} credits`);Error handling
All non-2xx responses throw a ByeBouncerError (or subclass) with code, status, and detail.
import { ByeBouncer, InsufficientCreditsError, RateLimitError } from "@bye_bouncer/sdk";
try {
await client.verify("[email protected]");
} catch (err) {
if (err instanceof InsufficientCreditsError) {
console.error(`Out of credits (${err.creditsRemaining ?? "?"} left)`);
} else if (err instanceof RateLimitError) {
console.error(`Rate limited, retry after ${err.retryAfterSeconds}s`);
} else {
throw err;
}
}API reference
The supported methods are listed below. Endpoints are relative to /api/v1;
see the public API documentation for
complete setup and REST examples.
| Method | Endpoint | Description |
|--------|----------|-------------|
| verify(email) | POST /verify | Verify a single email |
| verifyIP(ip) | POST /verify-ip | Analyze a single IP |
| verifyPhone(phone, options) | POST /verify-phone | Validate and enrich a phone number |
| addPhoneBlacklist(options) | POST /phone/blacklist | Add a number to your blacklist |
| removePhoneBlacklist(phone, country) | DELETE /phone/blacklist | Remove a number from your blacklist |
| credits() | GET /credits | Get balance |
| bulk(options) | POST /bulk | Enqueue a bulk job |
| bulkStatus(id) | GET /bulk/{id} | Fetch job |
| bulkCancel(id) | DELETE /bulk/{id} | Cancel |
| bulkDownloadUrl(id) | GET /bulk/{id}/download | Signed CSV URL |
| bulkSetWebhook(id, opts) | POST /bulk/{id}/webhook | Attach/rotate webhook |
| bulkWaitForCompletion(id, opts) | polls bulkStatus | Convenience helper |
| bulkAndWait(input, opts) | create+poll+download | Convenience helper |
The score-free data-validation methods (return validation-v1) let you pick one service at a time:
| Method | Endpoint | Credits |
|--------|----------|---------|
| validate(input) | POST /lead/verify | per channel; phone_mode: "local" \| "carrier" picks the phone service |
| validateEmail(email) | POST /verify-email | 1 |
| lookupIP(ip, options) | POST /verify-ip | 1 |
| validatePhoneLocal(phone, options) | POST /verify-phone/local | 1 |
| lookupPhoneCarrier(phone, options) | POST /verify-phone/carrier | 3 |
| lookupPhoneNetwork(phone, options) | POST /verify-phone/live | 6 |
validatePhone(phone, options) keeps the legacy behavior: carrier when configured, otherwise local.
Suggestions and domain lookups remain available through REST.
bulkIP() and bulkPhone() are retired and fail locally; bulk supports email only.
Use a live server key for credits, bulk and blacklist operations. Public keys
can verify email, IP and phone with an allowed Origin and an explicit allocation.
credits is spendable key balance; wallet_balance, when present, is the shared
account total. Buying credits does not automatically increase key allocations.
Options
new ByeBouncer({
apiKey: "bb_live_...", // required
baseUrl: "https://api.byebouncer.com", // default
timeoutMs: 30_000, // per-request timeout
fetch: customFetch, // optional custom transport
});Production use
timeoutMs applies to each HTTP request until its complete response body has
been read, including CSV downloads. Network timeouts propagate to the caller.
Bulk helpers raise bulk_not_completed for failed, cancelled or expired jobs
and for completed jobs without downloadable results. Prefer webhooks for large jobs.
Requests are not automatically retried: a timed-out verification may already have
consumed credits. To retry bulk creation safely, reuse the same idempotency key
with bulk(options, idempotencyKey).
bulkAndWait() does not accept an idempotency key. If creation needs safe
retries, use bulk() with a unique key per logical import and preserve that key
and its request body across retries, then poll and download separately.
Charges and limits
- Email: 1 credit per verification, including cached answers.
- IP: 1 credit per public, routable IP;
invalid_scoperesults are free. - Phone: 1 credit for a valid local result or 3 for a billable enriched result. Inconclusive and blacklisted results are free; billable cached answers are charged.
- HLR is an optional REST operation costing 6 additional credits per conclusive lookup.
- Bulk: email only, up to 5,000 unique emails per job. Credits are reserved on creation. Cancellation refunds unprocessed items; failed jobs refund the full debit.
Support
Local IP checks (requires the updated server)
const result = await client.lookupIP('8.8.8.8', {
checks: ['network_data', 'tor', 'geolocation', 'infrastructure', 'anonymization_catalog'],
});Omit checks to retain the existing default. The selection above performs no
DNS/rDNS/DNSBL calls during IP validation. Catalogs must be installed on the server;
absent or expired evidence is unavailable. no_match does not prove the absence of
a VPN or proxy. Public IP pricing is unchanged. Combined validation accepts
ip_checks in client.validate(...).
- Docs: https://byebouncer.com/docs
- Email: [email protected]
- Issues: https://github.com/fidelp27/byebouncer/issues
License
MIT © ByeBouncer
