Docs

Verify emails from the command line

A small CLI lives in the repository under sdks/cli. It is plain Node.js with no dependencies, it is not on npm yet, and it wraps the same one-request API the SDKs use. Run npm link ./sdks/cli once to get a validreach command, or call node sdks/cli/bin/validreach.js directly.

Before you start

You need Node 18 or newer and an API key from Settings → API keys. Keep the key in an environment variable named VALIDREACH_API_KEY; never commit it.

Verify one address

export VALIDREACH_API_KEY=vr_live_...

node sdks/cli/bin/validreach.js verify alice@example.com
# alice@example.com: valid
#   deliverable: yes
#   reason: mailbox accepted
#   credits used: 1

Disposable domains and credits

disposable answers from the known disposable-domain list and costs nothing. credits prints the balance, the lifetime consumed and the lifetime added for the key.

node sdks/cli/bin/validreach.js disposable alice@mailinator.com
node sdks/cli/bin/validreach.js credits

Use it in scripts

Pass --json to print the raw payload, and branch on the exit code instead of parsing text: 0 success, 1 request failed, 2 usage, 3 key rejected, 4 out of credits, 5 rate limited. The CLI never retries on its own, because a retry spends another credit.

if validreach verify "$email" --json > result.json; then
  jq -r .status result.json
else
  echo "verify failed with code $?" >&2
fi

Flags that change the result