Build clean email data
into anything.

Overview

The API base URL is:

Requests and responses use JSON unless you are uploading or downloading a file. All timestamps are ISO 8601 in UTC. API responses include X-API-Version: 1.0 and are never cached.

Authentication

Create a named key in your dashboard and send it as a Bearer token. The full secret is shown only once.

Authorization: Bearer g2v_ev_live_YOUR_KEY

Limits & credits

• 50 free verification credits per UTC calendar month
• Purchased pay-as-you-go credits remain valid for 365 days
• Free monthly credits are used before purchased credits
• One credit per address, whether the result is valid, risky, or invalid
• Technical verifier or platform failures are automatically refunded
• 25 authenticated API requests per minute per key
• Up to 1,000 unique addresses per API token in each bulk job, subject to available credits
• API result rows remain retrievable for 24 hours after completion

View pay-as-you-go credit packages.

Verify one address

Submit one email string. Every successful response uses only safe, catch_all, or unsafe. Malformed, invalid, disposable, greylisted, and inconclusive addresses all normalize to unsafe on this base endpoint.

cURL

curl -X POST https://emailverifier.g2v.org/api \
  -H "Authorization: Bearer g2v_ev_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"hello@example.com"}'

Node.js

const response = await fetch("https://emailverifier.g2v.org/api", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.G2V_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ email: "hello@example.com" })
});

const result = await response.json();

200 response · safe

{
  "request_id": "f3d8...",
  "status": "safe",
  "data": {
    "email": "hello@example.com",
    "status": "safe"
  },
  "status_url": "/api/status/f3d8...",
  "credits": {
    "charged": 1,
    "limit": 50,
    "used": 1,
    "remaining": 49,
    "resets_at": "2026-09-01T00:00:00.000Z"
  }
}

200 response · catch_all

{
  "request_id": "a91c...",
  "status": "catch_all",
  "data": {
    "email": "sales@example.com",
    "status": "catch_all"
  },
  "status_url": "/api/status/a91c..."
}

200 response · unsafe

{
  "request_id": "b72e...",
  "status": "unsafe",
  "data": {
    "email": "missing@example.com",
    "status": "unsafe"
  },
  "status_url": "/api/status/b72e..."
}

Get detailed verification status

Use the status_url returned by the base endpoint when your system needs the exact mailbox classification, risk flags, diagnosis, and check time. Authentication uses the same Bearer API key, and an account can access only its own requests. Retrieve details within 24 hours; after that the submitted address is redacted and this endpoint returns 410 details_expired.

curl https://emailverifier.g2v.org/api/status/REQUEST_ID \
  -H "Authorization: Bearer g2v_ev_live_YOUR_KEY"

{
  "request_id": "f3d8...",
  "state": "completed",
  "data": {
    "email": "hello@example.com",
    "status": "valid",
    "verdict": "safe",
    "safe_to_send": true,
    "disposable": false,
    "role_based": false,
    "free_provider": false,
    "catch_all": false,
    "greylisted": false,
    "diagnosis": "Mailbox exists and is active. Safe to send.",
    "checked_at": "2026-08-11T12:00:00.000Z"
  }
}

Download the CSV template

This public endpoint downloads a ready-to-complete UTF-8 CSV file. Keep the first-row header exactly email, then add one email address per row beneath it. Do not put multiple addresses in one cell.

cURL

curl -L https://emailverifier.g2v.org/api/bulk/template \
  -o g2v-email-verifier-template.csv

Create a bulk job

Send up to 1,000 unique addresses per API token in one JSON request or CSV/TXT upload. Duplicate addresses are removed before quota is reserved, and the account must have enough available credits. Processing is asynchronous.

JSON list

curl -X POST https://emailverifier.g2v.org/api/bulk \
  -H "Authorization: Bearer g2v_ev_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"leads.csv","emails":["one@example.com","two@example.com"]}'

File upload

curl -X POST https://emailverifier.g2v.org/api/bulk \
  -H "Authorization: Bearer g2v_ev_live_YOUR_KEY" \
  -F "file=@./contacts.csv"

202 response

{
  "job_id": "cb71...",
  "status": "queued",
  "total": 2,
  "status_url": "/api/bulk/cb71..."
}

Get job status and results

Poll this endpoint until status is COMPLETED or PARTIAL. The response includes progress, aggregate counts, and ordered result rows. Download or import the rows within 24 hours after completion. G2V then redacts submitted addresses and the client-supplied filename while preserving aggregate operational logs; an expired CSV download returns HTTP 410.

curl https://emailverifier.g2v.org/api/bulk/JOB_ID \
  -H "Authorization: Bearer g2v_ev_live_YOUR_KEY"

Download the same results as CSV from /api/bulk/{job_id}/download.

Get monthly usage

curl https://emailverifier.g2v.org/api/usage \
  -H "Authorization: Bearer g2v_ev_live_YOUR_KEY"

Detailed status reference

These five internal mailbox statuses appear only in the detailed endpoint, bulk results, and dashboard. The base POST /api remains limited to safe, catch_all, or unsafe.

Verdicts and safety fields

Important: a catch-all domain accepts messages sent to arbitrary recipients, so the individual mailbox may still be absent. Verification reduces risk but cannot guarantee delivery, engagement, consent, identity, or future availability.

Error format

{
  "error": {
    "code": "verification_credits_exhausted",
    "message": "No verification credits are currently available for this account."
  }
}