# Verifly for AI Agents

Verifly is a pay-as-you-go email verification API built so an AI agent can use it end to end with no human in the loop: discover it, self-register for a key, verify emails (single, batch, or async bulk), clean and extract lists, and pay for more credits with crypto. This page is the machine-readable guide to that workflow.

- Base URL: `https://verifly.email/api/v1`
- Auth: `Authorization: Bearer vf_<key>` (or `VERIFLY_API_KEY` env var)
- Hosted MCP server: `https://verifly.email/mcp` (Streamable HTTP, POST, same Bearer header)
- MCP npm package: `npx verifly-mcp-server` (env `VERIFLY_API_KEY`)
- OpenAPI: `https://verifly.email/openapi.json`
- Human + per-tool docs: `https://verifly.email/mcp`
- Never expose API keys in prompts, logs, screenshots, or generated code.

## 1. Discover

- Tool manifest: `https://verifly.email/verifly-tool-manifest.json`
- OpenAPI: `https://verifly.email/openapi.json` (also `/.well-known/openapi.json`)
- LLM index: `https://verifly.email/llms.txt` and `https://verifly.email/llms-full.txt`
- MCP server + every tool: `https://verifly.email/mcp`

## 2. Self-register (no human)

Mint a brand-new account and API key. Disposable email domains are rejected; password is min 8 chars. The new account starts with 100 free credits. The `api_key.key` is returned ONCE — store it.

```bash
curl -s -X POST "https://verifly.email/api/v1/autonomous/register" \
  -H "Content-Type: application/json" \
  -d '{"email":"my-agent@example.com","password":"a-strong-password"}'
```

MCP equivalent: tool `register_account` with `{ "email": "...", "password": "..." }`.

## 3. Verify

Single address (1 credit):

```bash
curl -s "https://verifly.email/api/v1/verify?email=lead@example.com" \
  -H "Authorization: Bearer vf_your_api_key"
```

Batch, synchronous, small lists (1 credit/email):

```bash
curl -s -X POST "https://verifly.email/api/v1/verify/batch" \
  -H "Authorization: Bearer vf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"emails":["a@test.com","b@test.com"]}'
```

Act on the verdict: keep `recommendation: "safe_to_send"`, drop `do_not_send`, review `risky`.

## 4. Bulk (async, large lists)

Submit a job, poll it, then fetch results (1 credit/email):

```bash
# submit
curl -s -X POST "https://verifly.email/api/v1/verify/bulk" \
  -H "Authorization: Bearer vf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"emails":["a@test.com","b@test.com"],"webhook_url":"https://you.example/webhook"}'
# -> { "job_id": "...", "status": "pending" }

# poll until status == "completed"
curl -s "https://verifly.email/api/v1/jobs/JOB_ID" -H "Authorization: Bearer vf_your_api_key"

# fetch results
curl -s "https://verifly.email/api/v1/jobs/JOB_ID/results" -H "Authorization: Bearer vf_your_api_key"
```

MCP tools: `submit_bulk` -> `get_job_status` -> `get_job_results` (or `list_jobs` to find past jobs). Pass a public HTTPS `webhook_url` to skip polling.

## 5. List hygiene (free)

- Clean before verifying — dedupe, drop invalid syntax, strip disposable/role: `POST /api/v1/clean` (MCP `clean_email_list`).
- Pull addresses out of free-form text: `POST /api/v1/extract` (MCP `extract_emails`).
- Diagnose a domain's MX/SPF/DMARC: `GET /api/tools/domain-health?domain=example.com` (MCP `check_domain_health`).

## 6. Check balance and pay (agent-native crypto)

```bash
# how many credits are left?
curl -s "https://verifly.email/api/v1/credits" -H "Authorization: Bearer vf_your_api_key"

# what can I buy?
curl -s "https://verifly.email/api/v1/billing?action=packages" -H "Authorization: Bearer vf_your_api_key"

# buy with crypto -> returns a raw wallet address an agent can pay autonomously
curl -s -X POST "https://verifly.email/api/v1/billing" \
  -H "Authorization: Bearer vf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"package_id":"starter","method":"crypto","currency":"USDT"}'
```

`method:"crypto"` with a `currency` (BTC, ETH, LTC, USDT, USDC) returns a raw wallet `address` + `amount` + `qr_code` — pay it from a wallet with no browser; credits are added automatically once the payment confirms. `method:"stripe"` returns a hosted `checkout_url` that needs a human to enter card details.

MCP tools: `get_credits`, `get_packages`, `buy_credits`. Account profile + usage: `get_account`, `get_usage`.

## MCP tool reference (15 tools)

Each tool has its own page at `https://verifly.email/mcp/<tool>` with input schema, a `tools/call` example, the equivalent curl, and the credit cost.

| Tool | REST endpoint | Cost | Page |
|------|---------------|------|------|
| verify_email | GET /api/v1/verify | 1 credit | /mcp/verify_email |
| verify_batch | POST /api/v1/verify/batch | 1 credit/email | /mcp/verify_batch |
| clean_email_list | POST /api/v1/clean | free | /mcp/clean_email_list |
| extract_emails | POST /api/v1/extract | free | /mcp/extract_emails |
| check_domain_health | GET /api/tools/domain-health | free | /mcp/check_domain_health |
| get_credits | GET /api/v1/credits | free | /mcp/get_credits |
| submit_bulk | POST /api/v1/verify/bulk | 1 credit/email | /mcp/submit_bulk |
| get_job_status | GET /api/v1/jobs/{id} | free | /mcp/get_job_status |
| get_job_results | GET /api/v1/jobs/{id}/results | free | /mcp/get_job_results |
| list_jobs | GET /api/v1/jobs | free | /mcp/list_jobs |
| get_usage | GET /api/v1/usage | free | /mcp/get_usage |
| get_account | GET /api/v1/account | free | /mcp/get_account |
| get_packages | GET /api/v1/billing?action=packages | free | /mcp/get_packages |
| buy_credits | POST /api/v1/billing | free to call | /mcp/buy_credits |
| register_account | POST /api/v1/autonomous/register | free (no key) | /mcp/register_account |

Connect over MCP:

```json
{
  "mcpServers": {
    "verifly": {
      "url": "https://verifly.email/mcp",
      "headers": { "Authorization": "Bearer vf_your_api_key" }
    }
  }
}
```

Or locally with the npm package:

```json
{
  "mcpServers": {
    "verifly": {
      "command": "npx",
      "args": ["-y", "verifly-mcp-server"],
      "env": { "VERIFLY_API_KEY": "vf_your_api_key" }
    }
  }
}
```

## Result fields to branch on

- `result`: `deliverable` | `undeliverable` | `risky` | `unknown`
- `recommendation`: `safe_to_send` | `do_not_send`
- `details`: `is_disposable`, `is_role_account`, `is_catch_all`, `is_free_provider`, `mx_records`, `smtp_valid`, ...
- HTTP `402` means out of credits — call `buy_credits` then retry.

## Links

- MCP server: https://verifly.email/mcp
- Tool manifest: https://verifly.email/verifly-tool-manifest.json
- OpenAPI: https://verifly.email/openapi.json
- agents.txt: https://verifly.email/agents.txt
- llms.txt: https://verifly.email/llms.txt
- Docs: https://verifly.email/docs
- GitHub (MCP server): https://github.com/james-sib/verifly-mcp-server
- GitHub (CLI): https://github.com/james-sib/verifly-cli
- Support: hello@veriflyemail.com