Installation

pip install email-validator-cli

Or download the standalone script:

Download ZIP PyPI

Requirements: Python 3.8+. No external dependencies — uses only the standard library (urllib, json, csv, argparse). Works on Linux, macOS, Windows, and in Docker.

Setup

Get your API key from the Dashboard, then:

email-validator setup

Or configure non-interactively:

# Environment variable
export EV_API_KEY=ev_your_key_here

# Or config file (~/.email-validator.conf)
api_key=ev_your_key_here

# Or CLI flag
email-validator verify user@domain.com --api-key ev_your_key_here

Quick Start

Verify a single email

email-validator verify user@domain.com
#   ✓ user@domain.com           valid        conf:high mx:gmail-smtp-in.l.google.com 234ms

Pipe from stdin

cat emails.txt | email-validator verify --stdin
#   ✓ user1@domain.com          valid        234ms
#   ✗ user2@domain.com          invalid      Email does not exist
#   ⚠ user3@yahoo.com           risky        Verifly: 87% confidence

Export CSV

email-validator verify --file subscribers.txt --format csv --output results.csv

Line-delimited JSON (jq compatible)

cat leads.txt | email-validator verify --stdin --format jsonl | jq '.status'

Account & credits

email-validator account
# Account:  user@example.com
# Plan:     Basic
# Credits:  4500 remaining (of 5000)

email-validator credits
# ✓ 4500 credits

Verify Command Flags

Flag	Description
`--stdin`	Read emails from stdin (pipe)
`--file`, `-f PATH`	Read emails from file (skip lines starting with #)
`--format`, `-F fmt`	Output: `table`, `json`, `csv`, `jsonl`
`--output`, `-o PATH`	Write output to file
`--quiet`, `-q`	Minimal output (email<TAB>status)
`--api-key`, `-k KEY`	Override API key for this command

Auto-detection: When output is piped (e.g. | jq), the format automatically switches to jsonl. For interactive terminal use, it defaults to table.

Email Status Values

Status	Meaning	Credit Cost
`valid`	Mailbox confirmed exists	1 credit
`invalid`	Mailbox does not exist	1 credit
`risky`	Low confidence result (Yahoo, AOL, etc.)	Free
`catch_all`	Domain accepts all mail (can't confirm)	Free
`disposable`	Temporary/disposable email provider	Free
`unknown`	Could not determine (network/DNS error)	Free

CI/CD & Automation Examples

GitHub Actions

# .github/workflows/validate.yml
- name: Validate email list
  run: |
    pip install email-validator-cli
    email-validator verify --file subscribers.txt --format csv --output validated.csv
  env:
    EV_API_KEY: ${{ secrets.EV_API_KEY }}

Bash: filter valid emails only

email-validator verify --stdin --format jsonl < leads.txt \
  | jq -r 'select(.status=="valid") | .email' \
  > clean_leads.txt

Docker

FROM python:3.12-slim
RUN pip install email-validator-cli
ENTRYPOINT ["email-validator"]

Cron: nightly validation

# crontab
0 2 * * * /usr/local/bin/email-validator verify --file /data/list.csv \
           --output /data/validated.jsonl --format jsonl

Requirements

Python 3.8 or later
An active Email Validator account with API key
Verified emails consume credits — free/risky/unknown statuses are free
Rate limit: 60 requests/minute per user

CLI Tool