API Integration Guide for Email Validation
Step-by-step guide to integrating PilotVerify's email validation API into your application with code examples in multiple languages.
API Integration Guide for Email Validation
This comprehensive guide will walk you through integrating PilotVerify's email validation API into your application, from authentication to handling responses.
Getting Started
1. Create an Account
Sign up at [PilotVerify.net](https://pilotverify.net) and purchase a credit pack. You'll receive API keys immediately after signup.
2. Obtain API Keys
Navigate to Dashboard → API Keys and create a new key:
1. Click "Create API Key"
2. Give it a descriptive name
3. Copy the key (starts with pv_)
4. Store it securely - it won't be shown again
3. Test Connection
Verify your API key works:
curl -X POST https://pilotverify.net/api/validate \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "test@example.com"}'
API Endpoints
Single Email Validation
Endpoint: POST /api/validate
Validates one email address at a time.
Request:
{
"email": "user@example.com",
"skipSMTP": false
}
Parameters:
Response:
{
"email": "user@example.com",
"status": "VALID",
"deliverability_score": 92,
"checks": {
"syntax": true,
"mx_records": true,
"smtp_valid": true,
"is_disposable": false,
"is_role_based": false,
"is_free_email": true,
"is_catch_all": false
},
"recommendation": "ACCEPT",
"risk_level": "LOW",
"processing_time_ms": 87
}
Batch Validation
Endpoint: POST /api/validate/batch
Validates multiple emails in one request.
Request:
{
"emails": [
"user1@example.com",
"user2@example.com",
"user3@example.com"
],
"skipSMTP": false
}
Response:
{
"results": [
{
"email": "user1@example.com",
"status": "VALID",
"deliverability_score": 95
},
{
"email": "user2@example.com",
"status": "INVALID",
"deliverability_score": 12
}
],
"summary": {
"total": 3,
"valid": 2,
"invalid": 1
}
}
Code Examples
JavaScript / Node.js
async function validateEmail(email) {
const response = await fetch('https://pilotverify.net/api/validate', {
method: 'POST',
headers: {
'x-api-key': process.env.PILOTVERIFY_API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify({ email })
})
if (!response.ok) {
throw new Error(Validation failed: ${response.statusText})
}
return await response.json()
}
// Usage
try {
const result = await validateEmail('user@example.com')
console.log(Status: ${result.status})
console.log(Score: ${result.deliverability_score})
} catch (error) {
console.error('Validation error:', error)
}
Python
import requests
import os
def validate_email(email):
url = 'https://pilotverify.net/api/validate'
headers = {
'x-api-key': os.environ['PILOTVERIFY_API_KEY'],
'Content-Type': 'application/json'
}
data = {'email': email}
response = requests.post(url, json=data, headers=headers)
response.raise_for_status()
return response.json()
Usage
try:
result = validate_email('user@example.com')
print(f"Status: {result['status']}")
print(f"Score: {result['deliverability_score']}")
except requests.exceptions.RequestException as e:
print(f"Validation error: {e}")
PHP
function validateEmail($email) {
$url = 'https://pilotverify.net/api/validate';
$apiKey = getenv('PILOTVERIFY_API_KEY');
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'x-api-key: ' . $apiKey,
'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'email' => $email
]));
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode !== 200) {
throw new Exception("Validation failed");
}
return json_decode($response, true);
}
// Usage
try {
$result = validateEmail('user@example.com');
echo "Status: " . $result['status'] . "\n";
echo "Score: " . $result['deliverability_score'] . "\n";
} catch (Exception $e) {
echo "Validation error: " . $e->getMessage() . "\n";
}
?>
Ruby
require 'net/http'
require 'json'
def validate_email(email)
uri = URI('https://pilotverify.net/api/validate')
request = Net::HTTP::Post.new(uri)
request['x-api-key'] = ENV['PILOTVERIFY_API_KEY']
request['Content-Type'] = 'application/json'
request.body = { email: email }.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
raise "Validation failed" unless response.code == '200'
JSON.parse(response.body)
end
Usage
begin
result = validate_email('user@example.com')
puts "Status: #{result['status']}"
puts "Score: #{result['deliverability_score']}"
rescue => e
puts "Validation error: #{e.message}"
end
Error Handling
HTTP Status Codes
Error Response Format
{
"error": "Insufficient credits",
"code": "INSUFFICIENT_CREDITS",
"details": {
"current_credits": 0,
"required_credits": 1
}
}
Handling Errors
try {
const result = await validateEmail(email)
if (result.status === 'VALID') {
// Proceed with valid email
} else if (result.status === 'INVALID') {
// Show error to user
} else if (result.status === 'RISKY') {
// Require additional verification
}
} catch (error) {
if (error.response?.status === 402) {
// Handle insufficient credits
console.log('Please purchase more credits')
} else if (error.response?.status === 429) {
// Handle rate limiting
console.log('Too many requests, please slow down')
} else {
// Handle other errors
console.error('Validation failed:', error.message)
}
}
Best Practices
1. Cache Results
Cache validation results to avoid redundant API calls:
const cache = new Map()
async function validateEmailWithCache(email) {
// Check cache first
if (cache.has(email)) {
return cache.get(email)
}
// Validate and cache result
const result = await validateEmail(email)
cache.set(email, result)
// Expire cache after 24 hours
setTimeout(() => cache.delete(email), 24 * 60 * 60 * 1000)
return result
}
2. Implement Retry Logic
Handle temporary failures gracefully:
async function validateWithRetry(email, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await validateEmail(email)
} catch (error) {
if (i === maxRetries - 1) throw error
// Exponential backoff
await new Promise(resolve =>
setTimeout(resolve, Math.pow(2, i) * 1000)
)
}
}
}
3. Use Batch Endpoint for Multiple Emails
More efficient for validating multiple addresses:
// Instead of multiple single requests
for (const email of emails) {
await validateEmail(email) // Slow!
}
// Use batch endpoint
const results = await fetch('/api/validate/batch', {
method: 'POST',
headers: {
'x-api-key': API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify({ emails })
})
4. Monitor Usage
Track API usage and credit consumption:
// Log each validation
console.log(Validated ${email}: ${result.status})
// Check credits periodically
const response = await fetch('/api/credits', {
headers: { 'x-api-key': API_KEY }
})
const { credits } = await response.json()
if (credits < 100) {
console.warn('Low credits! Time to purchase more')
}
Rate Limits
Default rate limits:
Contact support for higher limits if needed.
Webhooks (Coming Soon)
Receive validation results via webhooks for async processing:
{
"event": "validation.completed",
"data": {
"batch_id": "batch_123",
"emails_validated": 1000,
"results_url": "https://pilotverify.net/api/batch/batch_123"
}
}
Support
Need help integrating?
[Get started with PilotVerify](/pricing) today!