Your first email check

From an empty folder to one paid screening call in six steps. One step spends real funds: at most $0.003 per run.

Screening only: syntax, DNS mail exchanger, disposable-domain list, role-account and typo heuristics. It does not verify that the mailbox exists or that mail will be delivered.

The path

  1. Evaluate fixed samples without paying: dated responses for every verdict, including the uncharged 503. Opening that page calls nothing.
  2. Install the public example files: five files served from this site, Node 22.9 or newer, npm install.
  3. Run one capped paid check: a wallet of your own with a little USDC on Base; the script authorizes at most $0.003 per run and never retries a payment.
  4. Interpret the result and use it in an integration: the fields, the errors and when you are charged, then the routing scripts.

Advanced, when you need it: the self-hosted n8n recipe, response-header size behind a proxy, failure handling and recovery.

1. Install

Node 22.9 or newer. Fetch the five files of the example folder (the script below, the lead-routing scripts and a package.json pinned to the versions our own service is built and tested with) and install:

mkdir paywallwatch-quickstart && cd paywallwatch-quickstart
curl -fsSLO https://paywallwatch.com/quickstart/first-check.ts
curl -fsSLO https://paywallwatch.com/quickstart/paid-check.ts
curl -fsSLO https://paywallwatch.com/quickstart/lead-routing.ts
curl -fsSLO https://paywallwatch.com/quickstart/route-lead.ts
curl -fsSLO https://paywallwatch.com/quickstart/package.json
npm install

Or, in a project of your own: pnpm add @x402/fetch@2.28.0 @x402/evm@2.28.0 viem@2.57.7 and pnpm add -D tsx@4.23.15, then copy the script below.

2. A wallet for the script

Generate a key for this purpose on your own machine and keep it in a .env file that your repository ignores. Never commit it, and never put a private key in a browser page: the script runs server-side.

node -e "import('viem/accounts').then(m => console.log('BUYER_EVM_PK=' + m.generatePrivateKey()))" >> .env
echo .env >> .gitignore
node --env-file=.env -e "import('viem/accounts').then(m => console.log(m.privateKeyToAccount(process.env.BUYER_EVM_PK).address))"

The third command prints the wallet's address, which is what you fund.

3. Fund it

Send USDC on Base (network eip155:8453) to that address. $1 covers 333 checks at $0.003; $3 covers a thousand. The wallet needs no ETH: the facilitator pays the gas. Fund only what you are willing to spend from this key.

There is no public test instance. The public API settles on mainnet only, so the first run is a real check at $0.003; the script's cap means a run can never cost more than that. (The script also accepts PAYWALLWATCH_URL pointing at a local copy of the service that settles on Base Sepolia, which is how we test it ourselves.)

4. Run the check

This step spends real funds. The script makes one payment attempt and pays exactly the amount in the 402 terms: at most $0.003 per run. It previews terms unpaid, then validates the actual signing terms against its MAX_CHARGE_USD cap, USDC asset and expected network. It never retries a payment on its own.

node --env-file-if-exists=.env --import tsx first-check.ts jane@iana.org

Expected output: the terms, then the settlement (transaction hash, network, payer) and the verdict.

5. Read the response

FieldMeaning
verdictdomain_accepts_mail, risky, disposable, undeliverable or unknown (only with a 503).
reasonsWhy: invalid_syntax, domain_not_found, null_mx, no_mail_exchanger, no_mx_record_only_a_record, dns_lookup_failed, disposable_domain, typo_suspected.
suggestionA corrected address when a common typo is suspected; ask the person to confirm it.
dns_status, has_mxWhat DNS said about the domain. A mail exchanger means the domain accepts mail, not that the mailbox exists.
role_account, free_providerFlags for your own rules. They never change the verdict.
mailbox_verifiedAlways false. No SMTP conversation takes place.

Worked examples for every verdict are on the sample page.

6. Errors, and when you are charged

StatusWhat it meansCharge
402, no payment sentThe terms. Expected on the first request.none
402 after a paymentThe payment was rejected (signature, balance, wrong network); the body says why.none
400The payment carried no usable email. Refused before the facilitator is asked.none
503 with Retry-AfterThe DNS lookup failed; nothing is known about the domain. Retry later yourself.none: settlement is cancelled
200The screening result, with the settlement in PAYMENT-RESPONSE.$0.003
5xxA fault in the service or delivery path.Handler failures before settlement are uncharged; otherwise reconcile before retrying.

The result is computed first and returned only once settlement succeeds. If settlement fails after the check ran, you get a 402 with the reason instead of the result, and you are not charged.

If a response is lost or a facilitator times out, settlement may be uncertain. Check the transaction before retrying; a fresh authorization can charge again.

To prove the payment path before a real check, GET https://api.paywallwatch.com/v1/ping does the same dance for $0.01 and returns the server time.

Behind a proxy: response-header size

Response-header size. The unpaid 402 of the email route carries the terms and the output schema in its PAYMENT-REQUIRED header: about 4.5 KB, and about 5.2 KB of response headers in all with the server's own. Those are the sizes of the normalized header block as measured on 2026-10-28; a raw capture on the wire differs by the transport's framing and by any header a CDN or proxy adds. A client that reads the API directly, as the script does, handles that. For a proxy between your client and the API we recommend a response-header budget of 8 KiB or more for the response as measured (NGINX: proxy_buffer_size 8k; its default is one memory page, 4 KiB on many platforms, and the email route's 402 does not fit a 4 KiB buffer, after which NGINX treats the response as invalid). That is a configuration recommendation for the measured size, not the smallest value that could work and not an assurance that every proxy or client accepts it. The ping route's 402 fits a 4 KiB buffer. We have not tested every client, SDK or proxy, and we have not run NGINX against this service: these are the measured sizes and NGINX's documented rule.

The script

This is first-check.ts, served as plain text at https://paywallwatch.com/quickstart/first-check.ts; a test keeps this page equal to the served file. The other files from step 1 build on it: paid-check.ts is the same guarded call as a function, lead-routing.ts turns a result into a decision (route, confirm, hold, drop, retry later) and is pure, and route-lead.ts runs both for one lead (npm run route-lead -- jane@iana.org --name Jane, or offline from a saved result with --from-json, no payment).

// PaywallWatch quickstart: one paid email check, one payment attempt, a charge cap.
//
//   node --env-file-if-exists=.env --import tsx first-check.ts jane@iana.org
//
// Needs BUYER_EVM_PK in .env: a private key generated for this purpose, holding a little USDC on Base. It stays in .env
// on your machine: never in a browser, never in a repository. The facilitator pays the gas, so the wallet needs no ETH.
// Optional: PAYWALLWATCH_URL to point at a local copy of the service that settles on Base Sepolia.
import { wrapFetchWithPayment, x402Client, decodePaymentResponseHeader } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const MAX_CHARGE_USD = 0.003; // the script refuses to pay more than this for one check; the route costs $0.003
const origin = process.env.PAYWALLWATCH_URL ?? "https://api.paywallwatch.com";
const localTest = ["localhost", "127.0.0.1"].includes(new URL(origin).hostname);
const expectedNetwork = localTest ? "eip155:84532" : "eip155:8453";
const expectedAsset = localTest ? "0x036cbd53842c5426634e7929541ec2318f3dcf7e" : "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
const email = process.argv[2];
if (!email) { console.error("usage: first-check.ts <email>"); process.exit(2); }
const pk = process.env.BUYER_EVM_PK;
if (!pk || !pk.startsWith("0x")) { console.error("BUYER_EVM_PK is not set. Put it in .env, never in code and never in a browser."); process.exit(2); }

const url = `${origin}/v1/email/verify?email=${encodeURIComponent(email)}`;

// 1. Read the terms without paying. An unpaid request answers 402 with the price; nothing is charged.
const unpaid = await fetch(url);
if (unpaid.status !== 402) { console.error(`expected 402 with the terms, got ${unpaid.status}: ${(await unpaid.text()).slice(0, 200)}`); process.exit(1); }
const terms = JSON.parse(atob(unpaid.headers.get("PAYMENT-REQUIRED") ?? "")) as { accepts: { network: string; amount: string; extra?: { name?: string } }[] };
const evm = terms.accepts.find(a => a.network.startsWith("eip155:"));
if (!evm) { console.error("no EVM payment option in the terms"); process.exit(1); }
const usd = Number(evm.amount) / 1_000_000; // USDC has six decimals
console.log(`terms: ${usd.toFixed(6)} ${evm.extra?.name ?? "USDC"} on ${evm.network}`);
if (!Number.isFinite(usd) || usd <= 0 || usd > MAX_CHARGE_USD) { console.error(`refusing to pay ${usd}: above MAX_CHARGE_USD ${MAX_CHARGE_USD}`); process.exit(1); }

// 2. Pay once. wrapFetchWithPayment signs one USDC authorization for exactly the amount in the terms and sends the
//    request once more with it. It does not loop: a rejected payment comes back as a 402 with the reason, uncharged.
const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(privateKeyToAccount(pk as `0x${string}`)));
client.registerPolicy((version, requirements) => version === 2 ? requirements.filter(r =>
  r.scheme === "exact" && r.network === expectedNetwork &&
  r.asset.toLowerCase() === expectedAsset && /^\d+$/.test(r.amount) &&
  BigInt(r.amount) > 0n && BigInt(r.amount) <= BigInt(Math.floor(MAX_CHARGE_USD * 1_000_000))
) : []);
const paidFetch = wrapFetchWithPayment(fetch, client);
const res = await paidFetch(url);
const text = await res.text();
let body: Record<string, unknown> = {};
try { body = JSON.parse(text) as Record<string, unknown>; } catch { /* a non-JSON body is reported below as text */ }
const settlement = res.headers.get("PAYMENT-RESPONSE");

// 3. Read the answer. Only a 200 is charged, and it carries the settlement in PAYMENT-RESPONSE.
if (res.status === 200) {
  console.log(`charged ${usd.toFixed(6)} USDC:`, settlement ? decodePaymentResponseHeader(settlement) : "(no PAYMENT-RESPONSE header)");
  console.log(`verdict ${String(body.verdict)} for ${String(body.email)}; reasons ${JSON.stringify(body.reasons)}; suggestion ${String(body.suggestion ?? "none")}`);
  console.log("mailbox_verified:", body.mailbox_verified, "(screening never verifies that the mailbox exists)");
} else if (res.status === 503) {
  console.log(`503: the DNS lookup failed; not charged. Retry-After ${res.headers.get("Retry-After")} s. Run again later: this script does not retry on its own.`);
} else if (res.status === 402) {
  console.log(`402 after payment: not charged. ${String(body.error ?? text.slice(0, 200))}`);
} else if (res.status === 400) {
  console.log(`400: not charged. ${String(body.error)}`);
} else {
  console.log(`${res.status}: settlement status uncertain; reconcile before retrying. ${text.slice(0, 200)}`);
}
process.exit(res.status === 200 ? 0 : 1);

From n8n (self-hosted only)

A workflow can run the same check per lead with n8n's built-in Execute Command node calling route-lead.ts, then branch on the decision with a Switch node (route, confirm, hold, drop, retry later). The node runs a shell command where the workflow executes, so everything the command needs must live there.

Cost. Each script invocation screens one address and authorizes at most $0.003. The command runs once per item, so a run with several leads, a retry or a repeated execution makes several invocations; the cap is per invocation, not a limit on the workflow. The script never retries a payment, and a 503 or a rejected payment is not charged.

Environment and setup: self-hosted n8n, where the files go, the wallet key, enabling the node
The nodes and the three snippets

The nodes

Five nodes in a row, then the Switch. Keep the names: the parser refers to the guard node by name.

  1. Trigger: a Manual Trigger to test with, or your form or webhook trigger.
  2. Lead (Edit Fields, also called Set): the string fields email, name and source, one item per lead. Replace the sample values with your form, CRM or webhook fields.
  3. Guard the address (Code, JavaScript, Run Once for All Items): the first snippet below. Change its first line, QUICKSTART_DIR, to the absolute Linux path of the folder from step 1 where the command runs. It admits only a plain address, writes the configured folder onto every item (a lead field cannot override it) and links each output to its lead.
  4. Paid check (route-lead.ts) (Execute Command): switch Execute Once off, since n8n's default for this node is on and would run the command for the first lead only, dropping the rest; set the Command field to the second snippet with the field switched to Expression. It then runs once per item.
  5. Read the decision (Code, JavaScript, Run Once for All Items): the third snippet.
  6. Route by action (Switch, rules mode): five rules, each testing {{ $json.decision.action }} equals one of route, confirm, hold, drop and retry_later, with the outputs renamed to those values; connect each output to your CRM, mail or queue step.

Connect them in that order: the trigger into Lead, Lead into Guard the address, the guard into Paid check, Paid check into Read the decision, and that into Route by action.

Guard the input (the Guard the address node, verbatim from our workflow). The allow-lists keep quotes, spaces, backslashes and shell operators out of the two values the command receives, and the single quotes in the command make the admitted characters literal to a POSIX shell; the folder is a constant you set here, never lead data (the check is on the path string; the folder, its contents and any symlinks are yours to control):

// Change this one line: the absolute Linux path of the folder that holds route-lead.ts, its node_modules and its .env,
// where n8n runs the command (inside the container, or on the worker in queue mode). It is configured here, never
// taken from the lead, so incoming data cannot point the command somewhere else.
const QUICKSTART_DIR = "/opt/paywallwatch/quickstart";
// Allow-lists for the two values the single-quoted command line receives: a plain address and the configured path.
// Neither admits a quote, a space, a backslash or a shell operator, and the quotes make what they admit literal.
const plain = /^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/;
const absDir = /^(?:\/[A-Za-z0-9._-]+)+$/;
if (!absDir.test(QUICKSTART_DIR)) throw new Error(`QUICKSTART_DIR must be an absolute Linux path of letters, digits and . _ - (no backslash, drive letter, space or trailing slash), got ${JSON.stringify(QUICKSTART_DIR)}`);
return $input.all().map((item, i) => {
  const email = String(item.json.email ?? "").trim();
  if (!plain.test(email)) throw new Error(`refusing to screen ${JSON.stringify(email)}: not a plain address`);
  // pairedItem links each output to the lead that produced it, so later nodes can find that lead by item linking.
  return { json: { ...item.json, email, quickstartDir: QUICKSTART_DIR }, pairedItem: { item: i } };
});

The command (the Paid check node). Both values are single-quoted: a POSIX shell keeps every character inside single quotes literal, and the guard admits no single quote. Supported on a POSIX shell only:

cd '{{ $json.quickstartDir }}' && node --env-file-if-exists=.env --import tsx route-lead.ts '{{ $json.email }}'

Read the result (the Read the decision node). route-lead.ts prints one status line (check: HTTP 200, charged …) and then the JSON { lead, decision }, so JSON.parse(stdout) fails; this node parses from the first {, and finds each result's own lead through n8n's item linking ($('Guard the address').itemMatching(i)), so a run with several leads keeps every name and source with the right address:

// route-lead.ts prints one status line, then the JSON { lead, decision }. The command ran once per lead, so there is
// one item here per lead; n8n's item linking ($('Guard the address').itemMatching(i)) returns the guarded lead that
// produced item i. Fail-fast: a command failure (an error item from Continue on Fail, or a non-zero exit code),
// missing output, malformed JSON or a result for another address each stop this node with its own message naming
// the lead; no item is skipped and no lead is given another lead's result. The messages avoid ": " because n8n's
// Code node shows only the text after the first ": " as the message.
const oneLine = (s) => String(s ?? "").replace(/\s+/g, " ").replace(/:\s/g, " - ").slice(0, 200);
return $input.all().map((item, i) => {
  const lead = $('Guard the address').itemMatching(i).json;
  if (item.json.error !== undefined) throw new Error(`command failed for the lead ${lead.email} (Continue on Fail is not supported by this parser) - ${oneLine(item.json.error)}`);
  if (item.json.exitCode !== undefined && item.json.exitCode !== 0) throw new Error(`command failed for the lead ${lead.email} - exit code ${item.json.exitCode} - ${oneLine(item.json.stderr)}`);
  const out = String(item.json.stdout ?? "");
  const start = out.indexOf("{");
  if (start < 0) throw new Error(`no decision in the script output for the lead ${lead.email} - ${oneLine(out)}`);
  let parsed;
  try { parsed = JSON.parse(out.slice(start)); } catch (e) { throw new Error(`malformed JSON in the script output for the lead ${lead.email} - ${oneLine(e.message)}`); }
  if (!parsed || !parsed.lead || !parsed.decision) throw new Error(`malformed JSON in the script output for the lead ${lead.email} - no lead or decision`);
  if (parsed.lead.email !== lead.email) throw new Error(`the result for ${parsed.lead.email} is paired with the lead ${lead.email}`);
  return { json: { lead: { ...parsed.lead, name: lead.name ?? parsed.lead.name, source: lead.source ?? parsed.lead.source }, decision: parsed.decision, check: out.slice(0, start).trim() }, pairedItem: { item: i } };
});
Failure handling and recovery

Failure handling. The recipe is fail-fast and is written for the Execute Command node's default On Error setting, Stop Workflow (n8n's node settings reference, read 2026-10-29). If the command fails for a lead (a non-zero exit: the key missing, the service unreachable, terms refused, bad arguments), the node halts the execution with that error. What that leaves behind: the earlier invocations may already have settled successfully, while others may have returned an uncharged result (a 503 or a rejected payment is not charged); the failed invocation's settlement is uncertain if the failure was a transport failure after the payment was sent; and the leads after it were never processed. A workflow failure reverses no payment and proves no payment absent. Before another run, sort the leads into completed, failed and not yet processed, and reconcile any uncertain payment on chain before authorizing another attempt for it; then run only the leads that still need a check. Do not replay the whole batch: every replayed completed lead is a new, potentially chargeable invocation. The other two On Error settings are not supported by this recipe: with Continue (using regular output) the node passes an error item without output on to the parser, which rejects it with "command failed" instead of producing a decision or giving another lead its result; with Continue (using error output) the failures go to a separate error output, and an unconnected error branch leaves them unhandled while the successful items continue. Neither continuation mode works here without separately designed and tested handling; we have replayed the regular-output case against a local stub and have not tested the error-output case. The parser's four errors name the lead and the failure: command failed, no decision in the output, malformed JSON, or a result paired with the wrong address. Nothing is skipped and nothing is retried automatically.

An earlier version of this workflow was submitted to n8n's template library on 2026-10-28 and is under review; the submitted copy predates the corrections on this page, which is the current recipe. No listing exists yet.