API Reference

Complete email checker API reference. Endpoints, parameters, response codes for email verification and validation.

The EmailVerify API is a RESTful service that provides powerful email verification capabilities. All API requests should be made over HTTPS.

Base URL

https://api.emailverify.ai/v1

Authentication

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Get your API key from the EmailVerify dashboard.

Example

curl -X POST https://api.emailverify.ai/v1/verify \
  -H "Authorization: Bearer bv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

Rate Limits

Plan	Requests/Hour	Requests/Day
Free	100	1,000
Starter	1,000	10,000
Professional	10,000	100,000
Enterprise	Custom	Custom

Rate limit information is included in response headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed
`X-RateLimit-Remaining`	Requests remaining in window
`X-RateLimit-Reset`	Unix timestamp when limit resets

When rate limited, you'll receive a 429 Too Many Requests response:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "retry_after": 3600
  }
}

Endpoints

Single Email Verification

Verify a single email address with detailed results.

POST /verify

Request

{
  "email": "user@example.com",
  "smtp_check": true,
  "timeout": 5000
}

Parameters

Parameter	Type	Required	Default	Description
`email`	string	Yes	-	Email address to verify
`smtp_check`	boolean	No	`true`	Perform SMTP mailbox verification
`timeout`	integer	No	`5000`	Request timeout in milliseconds (max: 30000)

Response

{
  "email": "user@example.com",
  "status": "valid",
  "result": {
    "deliverable": true,
    "valid_format": true,
    "valid_domain": true,
    "valid_mx": true,
    "disposable": false,
    "role": false,
    "catchall": false,
    "free": false,
    "smtp_valid": true
  },
  "score": 0.95,
  "reason": null,
  "credits_used": 1
}

Response Fields

Field	Type	Description
`email`	string	The verified email address
`status`	string	Verification status: `valid`, `invalid`, `unknown`, `accept_all`
`result`	object	Detailed verification results
`score`	number	Confidence score (0.0 - 1.0)
`reason`	string	Reason for invalid/unknown status (nullable)
`credits_used`	integer	Number of credits consumed

Result Object Fields

Field	Type	Description
`deliverable`	boolean	Whether email can receive messages
`valid_format`	boolean	Whether email has valid syntax
`valid_domain`	boolean	Whether domain exists
`valid_mx`	boolean	Whether domain has MX records
`disposable`	boolean	Whether email is from disposable service
`role`	boolean	Whether email is role-based (info@, support@)
`catchall`	boolean	Whether domain accepts all emails
`free`	boolean	Whether email is from free provider
`smtp_valid`	boolean	Whether SMTP verification passed

Bulk Email Verification

Submit multiple email addresses for verification. Returns a job ID for tracking progress.

POST /verify/bulk

Request

{
  "emails": [
    "user1@example.com",
    "user2@example.com",
    "user3@example.com"
  ],
  "smtp_check": true,
  "webhook_url": "https://your-app.com/webhooks/emailverify"
}

Parameters

Parameter	Type	Required	Default	Description
`emails`	array	Yes	-	Array of email addresses (max: 10,000)
`smtp_check`	boolean	No	`true`	Perform SMTP verification
`webhook_url`	string	No	-	URL to receive completion notification

Response

{
  "job_id": "job_abc123xyz",
  "status": "processing",
  "total": 3,
  "processed": 0,
  "valid": 0,
  "invalid": 0,
  "unknown": 0,
  "credits_used": 3,
  "created_at": "2025-01-15T10:30:00Z"
}

Get Bulk Job Status

Check the status of a bulk verification job.

GET /verify/bulk/{job_id}

Response (In Progress)

{
  "job_id": "job_abc123xyz",
  "status": "processing",
  "total": 1000,
  "processed": 450,
  "valid": 380,
  "invalid": 50,
  "unknown": 20,
  "progress_percent": 45,
  "created_at": "2025-01-15T10:30:00Z"
}

Response (Completed)

{
  "job_id": "job_abc123xyz",
  "status": "completed",
  "total": 1000,
  "processed": 1000,
  "valid": 850,
  "invalid": 100,
  "unknown": 50,
  "progress_percent": 100,
  "created_at": "2025-01-15T10:30:00Z",
  "completed_at": "2025-01-15T10:35:00Z"
}

Job Status Values

Status	Description
`pending`	Job is queued
`processing`	Job is being processed
`completed`	Job finished successfully
`failed`	Job failed (see error field)

Get Bulk Job Results

Retrieve verification results for a completed bulk job.

GET /verify/bulk/{job_id}/results

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	100	Results per page (max: 1000)
`offset`	integer	0	Starting position
`status`	string	-	Filter by status: `valid`, `invalid`, `unknown`

Response

{
  "job_id": "job_abc123xyz",
  "total": 1000,
  "limit": 100,
  "offset": 0,
  "results": [
    {
      "email": "user1@example.com",
      "status": "valid",
      "result": {
        "deliverable": true,
        "disposable": false,
        "role": false
      },
      "score": 0.95
    },
    {
      "email": "user2@example.com",
      "status": "invalid",
      "result": {
        "deliverable": false,
        "reason": "mailbox_not_found"
      },
      "score": 0.10
    }
  ]
}

Check Credits

Get current credit balance and usage information.

GET /credits

Response

{
  "available": 9500,
  "used": 500,
  "total": 10000,
  "plan": "Professional",
  "resets_at": "2025-02-01T00:00:00Z",
  "rate_limit": {
    "requests_per_hour": 10000,
    "remaining": 9850
  }
}

Webhooks

Create Webhook

POST /webhooks

{
  "url": "https://your-app.com/webhooks/emailverify",
  "events": ["verification.completed", "bulk.completed"],
  "secret": "your-webhook-secret"
}

List Webhooks

GET /webhooks

Delete Webhook

DELETE /webhooks/{webhook_id}

Webhook Events

Event	Description
`verification.completed`	Single email verification completed
`bulk.completed`	Bulk job finished
`bulk.failed`	Bulk job failed
`credits.low`	Credits below threshold

Webhook Payload

{
  "event": "bulk.completed",
  "timestamp": "2025-01-15T10:35:00Z",
  "data": {
    "job_id": "job_abc123xyz",
    "status": "completed",
    "total": 1000,
    "valid": 850,
    "invalid": 100,
    "unknown": 50
  },
  "signature": "sha256=..."
}

Verification Status

Status	Meaning	Recommended Action
`valid`	Email exists and can receive messages	Safe to send
`invalid`	Email doesn't exist or can't receive	Remove from list
`unknown`	Could not determine validity	Retry later or use caution
`accept_all`	Domain accepts all emails (catch-all)	Monitor for bounces

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": "Additional context (optional)"
  }
}

HTTP Status Codes

Code	Description
`200`	Success
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn't exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error
`503`	Service Unavailable

Error Codes

Code	HTTP Status	Description
`INVALID_API_KEY`	401	API key is invalid or missing
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INSUFFICIENT_CREDITS`	403	Not enough credits
`INVALID_EMAIL`	400	Email format is invalid
`INVALID_REQUEST`	400	Request body is malformed
`JOB_NOT_FOUND`	404	Bulk job ID not found
`TIMEOUT`	504	Verification timed out

Best Practices

1. Use Environment Variables

Never hardcode API keys:

// Good
const apiKey = process.env.EMAILVERIFY_API_KEY;

// Bad - don't do this
const apiKey = 'bv_live_xxx';

2. Handle Rate Limits

Implement exponential backoff:

async function verifyWithRetry(email, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await verify(email);
    } catch (error) {
      if (error.code === 'RATE_LIMIT_EXCEEDED') {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw error;
    }
  }
}

3. Use Bulk for Multiple Emails

For verifying more than 10 emails, use the bulk endpoint:

// Good - single API call
const job = await client.verifyBulk(emails);

// Bad - many individual calls
for (const email of emails) {
  await client.verify(email);
}

4. Implement Webhooks for Bulk Jobs

Don't poll constantly; use webhooks:

// Submit with webhook
const job = await client.verifyBulk(emails, {
  webhookUrl: 'https://your-app.com/webhook',
});

API Reference

Node.js

Python

Go

PHP

Java

TypeScript

Quickstart Guide

Verification Types

Integration Guides

On this page