Command-line tool

The mobilevalidate command-line tool comes with the SDK. You can use it to check numbers and e-mail addresses, run bulk jobs from files and read results without writing code. In a terminal it prints tables. When piped, it prints NDJSON or JSON, so it fits into shell scripts and data pipelines.

#How do I run it?

Run it with npx, no install needed. --sandbox uses the public sandbox key, so this works without signing up:

npx mobilevalidate check +447700900001 +447700900002 [email protected] --sandbox

Without --sandbox, the key comes from MOBILEVALIDATE_API_KEY or --api-key. The API URL comes from --base-url or MOBILEVALIDATE_BASE_URL (default https://api.mobilevalidate.com). The CLI needs Node 18 or later and never prints your key.

#Which commands are there?

mobilevalidate check <number|email...|-> [--checks whatsapp,telegram,email] [--country GB] [--max-age 7d] [--wait 60] [--max-cost 1.00] [--json]
mobilevalidate check-email <address...|-> [--checks email,gmail]
mobilevalidate services [--json]
mobilevalidate lookup <lkp_id> [--wait 30]
mobilevalidate jobs create --file list.csv [--checks whatsapp,email] [--wait [seconds]]
mobilevalidate jobs get <job_id> [--wait 30]
mobilevalidate jobs results <job_id> [--registered true|false|null] [--limit 500]
mobilevalidate jobs download <job_id> [--format csv|ndjson] [--output results.csv]
mobilevalidate jobs cancel <job_id>
mobilevalidate webhooks verify --secret whsec_… --file body.json --headers headers.txt
mobilevalidate webhooks sign --secret whsec_… --file body.json
mobilevalidate webhooks list | test <endpoint_id>
mobilevalidate account | limits

• check takes numbers and e-mail addresses together. The default checks are whatsapp for numbers and email for addresses. With several --checks you get one table column per service; spam adds SPAM RISK and SPAM SCORE.
• jobs create --wait waits for the job (up to 600 s by default), then prints its results.
• jobs download writes the whole result file (CSV by default) to stdout, or streams it to --output <path>.
• check-email runs a job for bulk-only e-mail checks such as gmail and waits for it within --wait.
• webhooks sign prints signed headers for a body, so you can test your receiver locally; webhooks verify checks a delivery you captured.
• On an API error the CLI prints the code and message, then the API's suggestion, the docs link and the request ID.

#How do I feed it lists?

Use - to read from stdin, one identifier per line (commas and tabs also work):

cat numbers.txt | mobilevalidate check - --checks whatsapp,carrier
mobilevalidate jobs create --file leads.csv --wait

For CSV files, the CLI uses the phone, number, msisdn, mobile or e164 column and/or the email column. If none of these exists, it uses the first column, and cells containing @ are sent as e-mails. Lists longer than 100 entries belong in jobs create. Requests that look like sequential number ranges or generated e-mail lists are rejected by the API, whichever client sends them.

#What do the exit codes mean?

Exit code 3 lets a script tell "everything answered" apart from "some rows need another look" without parsing the output. Output formats: a table on a terminal, NDJSON (one result per line) when piped, and one JSON document with --json.