@proofwire/sdk

Email, phone and IP validation for TypeScript and JavaScript.

npm install @proofwire/sdk

import { Proofwire } from '@proofwire/sdk';

const proofwire = new Proofwire();  // reads PROOFWIRE_API_KEY

const result = await proofwire.email('[email protected]');

const action = result.match({
  valid:   () => 'send',
  invalid: () => 'drop',
  unknown: () => 'ask them to confirm the address',
});

The one design decision worth knowing

There is no result.valid.

That property would be the most convenient thing this package could offer and the most damaging, because if (result.valid) files every inconclusive answer under "not valid" — and inconclusive is the case the product exists to surface. A large minority of business mail servers accept every address you ask about, so nothing observable distinguishes a real mailbox from a fictional one. Most validators resolve that into "valid" and invoice you. You find out when it bounces.

So verdicts have three states, and match requires a handler for all three. Leave one out and it does not compile:

Property 'unknown' is missing in type '{ valid: ...; invalid: ...; }'
but required in type 'VerdictHandlers<string>'.

Inconclusive verdicts are never billed. You are not paying for the honesty.

What a result carries

const result = await proofwire.email('[email protected]');

result.verdict;              // 'unknown'
result.confidence;           // 0.52
result.attributes.catchAll;  // true
result.billing.credits_charged;  // 0
result.billing.reason;       // why it cost what it did, in plain language

for (const e of result.evidence) {
  console.log(`[${e.source}] ${e.detail} (${e.weight})`);
}
// [syntax] Address is syntactically well formed. (0.8)
// [mx]     1 MX record published. (1.9)
// [smtp]   Control probe: the server also accepted an address that cannot
//          exist, so its acceptance carries no information. (-1.4)

The control probe is the part worth noticing. Before trusting an acceptance, the server is asked about an address that cannot exist. If that is accepted too, the acceptance of the real one means nothing, and the verdict says so.

Retries and double charges

Every call carries an idempotency key, generated for you. A retry after a timeout replays the original response instead of spending again, so the client retries on 5xx and 429 by default without risking a double charge. A 429 is respected by the header it came with, not by a guess.

Pass your own key when a retry has to survive a process restart:

await proofwire.email(address, { idempotencyKey: `signup:${userId}` });

Errors

Separated by what you should do about them, because a malformed key is a deploy problem, an empty balance is a billing problem, and a 502 is a wait-and-retry problem.

| | | |---|---| | AuthenticationError | Key missing, malformed or revoked | | InsufficientCreditsError | Out of credits, or past your spend cap | | InvalidRequestError | The value or the request is wrong | | RateLimitError | Carries retryAfterSeconds | | ServiceError | Our side; already retried | | ConnectionError | Never reached us |

An inconclusive verdict is not among them. It is a successful response.

Configuration

new Proofwire({
  apiKey: 'pk_live_...',   // or PROOFWIRE_API_KEY
  timeoutMs: 15_000,
  maxRetries: 2,
});

A pk_test_ key answers from fixed sandbox fixtures and is never billed, which is what makes it usable in a test suite. proofwire.isTestMode tells you which kind you have.

Links

• Documentation
• Published accuracy benchmark, with the dataset downloadable so you can rerun it
• MCP server, if you are wiring this into an agent
• Source and issues

MIT.