EV Emaily

Emaily CLI Reference

The CLI is a zero-dependency command-line client for the Emaily REST API. Install it globally to get the emaily command on your PATH.

Install

bash
npm install -g .

(Or use npm link in your local workspace.) Requires Node.js 18+.

Authentication & base URL

The CLI authenticates with an API key. It resolves the key and base URL from, in order of precedence, CLI flags → environment variables → defaults.

text
--api-key <key>             or  EMAIL_VERIFIER_API_KEY
--url <url>                 or  EMAIL_VERIFIER_API_URL

Default base URL (production):

text
https://email-verifier-v61-production-gateway.emaily.workers.dev

Example:

bash
export EMAIL_VERIFIER_API_KEY=ev_live_...        # or set in PowerShell: $env:EMAIL_VERIFIER_API_KEY=...
emaily verify alice@example.com

Commands

verify <email> — verify one email (1 credit)

bash
emaily verify alice@example.com [--policy]
  • --policy — enable SPF/DMARC policy checks (default off).

verify-batch <emails...> — verify up to 10 (N credits)

bash
emaily verify-batch alice@example.com bob@example.org [--policy]

syntax <email> — syntax/normalization only (free)

bash
emaily syntax alice@example.com

domain <domain> — deep domain inspection (1 credit)

bash
emaily domain example.com [--dkim s1,s2] [--common-dkim] [--mta-sts]
  • --dkim s1,s2 — explicit DKIM selectors (comma-separated, max 8).
  • --common-dkim — try common DKIM selectors.
  • --mta-sts — fetch the MTA-STS policy file.

batch

bash
emaily batch submit <file> [--policy]        # submit an async batch (N credits)
emaily batch list [--limit N]                # list recent batches (free)
emaily batch status <batch_id>               # get batch status (free)
emaily batch results <batch_id>              # stream batch results
emaily batch export <batch_id> [outfile]     # download combined export JSON
emaily batch cancel <batch_id>               # cancel a running batch (releases credits)

batch submit reads a JSON file containing { "emails": [...], "include_policy_checks": ... }.

usage — show account quota (free)

bash
emaily usage

capabilities — show service capabilities (free)

bash
emaily capabilities

help — show this help

bash
emaily help

Global options

OptionEnv varDescription
--api-key <key>EMAIL_VERIFIER_API_KEYAPI key (ev_live_...).
--url <url>EMAIL_VERIFIER_API_URLAPI base URL.

Exit codes

  • 0 — success.
  • 1 — error (missing key, HTTP failure, rate-limited, unknown command, etc.).

Rate-limit handling

When the API returns 429, the CLI prints a message with the retry time (from retry_after_seconds or the Retry-After header) and exits 1. To continue you can wait for the window to reset or use a key with more headroom.