Overview
The API base URL is:
https://emailverifier.g2v.org/apiRequests 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 verification credits per UTC calendar month
- One credit per address, whether the result is valid, risky, or invalid
- Provider or platform failures are automatically refunded
- 25 authenticated API requests per minute per key
- Up to 50 unique addresses in one free-plan bulk job
/apiVerify one address
Submit one email string. A malformed address is returned as an invalid/undeliverable result rather than a transport error.
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
{
"request_id": "f3d8...",
"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 Active",
"checked_at": "2026-08-09T12:00:00.000Z"
},
"credits": {
"charged": 1,
"limit": 50,
"used": 1,
"remaining": 49,
"resets_at": "2026-09-01T00:00:00.000Z"
}
}/api/bulkCreate a bulk job
Send an array as JSON or upload a CSV/TXT file. Duplicate addresses are removed before quota is reserved. 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..."
}/api/bulk/{job_id}Get job status and results
Poll this endpoint until status is COMPLETED or PARTIAL. The response includes progress, aggregate counts, and ordered result rows.
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.
/api/usageGet monthly usage
curl https://emailverifier.g2v.org/api/usage \ -H "Authorization: Bearer g2v_ev_live_YOUR_KEY"
Verdicts and status
Valid, not disposable, and not greylisted.
Catch-all, greylisted, or otherwise needs review.
Invalid format or a mailbox diagnosed as invalid.
The provider could not make a reliable determination.
Important: verification reduces risk but cannot guarantee future delivery. Mailboxes and provider behavior can change after a check.
Error format
{
"error": {
"code": "monthly_quota_exceeded",
"message": "The 50-verification monthly allowance has been used."
}
}