Integrating Fuego Email Verification API with PHP
This guide will walk you through integrating the Fuego Email Verification API into your PHP applications. Whether you’re building a website, form handler, or custom application, this guide provides comprehensive implementation examples for PHP developers.
Prerequisites
- A Fuego account with an API key
- PHP 7.0 or higher
- Basic knowledge of PHP and HTTP requests
API Endpoint
The Fuego API endpoint for email verification is:
https://app.fuegoverify.com/api/v1/verify
Authentication
Authentication is done using an API token as a query parameter:
$apiToken = "YOUR_API_TOKEN";
// Token will be added to the URL as a query parameter
Method 1: Using cURL
PHP’s cURL extension provides a powerful and flexible way to make HTTP requests:
<?php
/**
* Verify an email address using the Fuego API with cURL
*
* @param string $email The email address to verify
* @return array The verification result
*/
function verifyEmail($email) {
$apiToken = "YOUR_API_TOKEN";
$url = "https://app.fuegoverify.com/api/v1/verify?email=" . urlencode($email) . "&token=" . urlencode($apiToken);
// Initialize cURL session
$ch = curl_init($url);
// Set cURL options
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true, // Return response as string
CURLOPT_FOLLOWLOCATION => true, // Follow redirects
CURLOPT_HTTPHEADER => [
'Content-Type: application/json'
],
CURLOPT_TIMEOUT => 30, // Timeout in seconds
CURLOPT_SSL_VERIFYPEER => true, // Verify SSL certificate
]);
// Execute the request
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error = curl_error($ch);
// Close cURL session
curl_close($ch);
// Handle errors
if ($error) {
throw new Exception("cURL Error: " . $error);
}
// Parse response
$result = json_decode($response, true);
if ($httpCode >= 400) {
$errorMessage = isset($result['error']) ? $result['error'] : "Unknown error";
if ($httpCode == 429) {
throw new Exception("Rate limit exceeded. Please try again later.");
} elseif ($httpCode == 401) {
throw new Exception("Invalid API token. Please check your credentials.");
} else {
throw new Exception("API Error (" . $httpCode . "): " . $errorMessage);
}
}
if (!$result) {
throw new Exception("Failed to parse API response");
}
return $result;
}
// Usage example
try {
$result = verifyEmail("[email protected]");
echo "Verification result: " . $result['result'] . "\n";
if ($result['result'] == "valid") {
echo "Email is valid!\n";
} else {
echo "Email is " . $result['result'] . ": " . ($result['reason'] ?? "No reason specified") . "\n";
}
// Access domain intelligence
if (isset($result['domain_insight'])) {
$company = $result['domain_insight']['name'] ?? 'Unknown';
$industry = $result['domain_insight']['industry'] ?? 'Unknown';
echo "Company: $company, Industry: $industry\n";
}
} catch (Exception $e) {
echo "Error: " . $e->getMessage() . "\n";
}
?>
Method 2: Using PHP’s file_get_contents()
For simpler applications or environments where cURL is not available, you can use PHP’s built-in file_get_contents() function:
<?php
/**
* Verify an email address using the Fuego API with file_get_contents
*
* @param string $email The email address to verify
* @return array The verification result
*/
function verifyEmail($email) {
$apiToken = "YOUR_API_TOKEN";
$url = "https://app.fuegoverify.com/api/v1/verify?email=" . urlencode($email) . "&token=" . urlencode($apiToken);
// Set stream context options
$context = stream_context_create([
'http' => [
'header' => "Content-Type: application/json\r\n",
'timeout' => 30,
'ignore_errors' => true, // Don't throw exceptions for HTTP errors
],
'ssl' => [
'verify_peer' => true,
'verify_peer_name' => true,
],
]);
// Make the request
$response = @file_get_contents($url, false, $context);
// Get HTTP response code
$httpCode = 0;
if (isset($http_response_header)) {
foreach ($http_response_header as $header) {
if (preg_match('/^HTTP\/\d\.\d\s+(\d+)/', $header, $matches)) {
$httpCode = intval($matches[1]);
break;
}
}
}
// Handle errors
if ($response === false) {
throw new Exception("Failed to connect to API");
}
// Parse response
$result = json_decode($response, true);
if ($httpCode >= 400) {
$errorMessage = isset($result['error']) ? $result['error'] : "Unknown error";
if ($httpCode == 429) {
throw new Exception("Rate limit exceeded. Please try again later.");
} elseif ($httpCode == 401) {
throw new Exception("Invalid API token. Please check your credentials.");
} else {
throw new Exception("API Error (" . $httpCode . "): " . $errorMessage);
}
}
if (!$result) {
throw new Exception("Failed to parse API response");
}
return $result;
}
// Usage example is the same as the cURL example
?>
Method 3: Using Guzzle HTTP Client
Guzzle is a popular PHP HTTP client that makes it easy to send HTTP requests and integrate with web services:
<?php
// First install Guzzle: composer require guzzlehttp/guzzle
require 'vendor/autoload.php';
use GuzzleHttp\Client;
use GuzzleHttp\Exception\ClientException;
use GuzzleHttp\Exception\ServerException;
use GuzzleHttp\Exception\ConnectException;
/**
* Verify an email address using the Fuego API with Guzzle
*
* @param string $email The email address to verify
* @return array The verification result
*/
function verifyEmail($email) {
$apiToken = "YOUR_API_TOKEN";
// Create a Guzzle HTTP client
$client = new Client([
'base_uri' => 'https://app.fuegoverify.com/api/v1/',
'timeout' => 30,
]);
try {
// Make the request
$response = $client->request('GET', 'verify', [
'headers' => [
'Content-Type' => 'application/json',
],
'query' => [
'email' => $email,
'token' => $apiToken,
],
'http_errors' => true, // Throw exceptions for HTTP errors
]);
// Get the response body
$body = $response->getBody()->getContents();
// Parse the JSON response
$result = json_decode($body, true);
if (!$result) {
throw new Exception("Failed to parse API response");
}
return $result;
} catch (ClientException $e) {
// 4xx errors
$response = $e->getResponse();
$statusCode = $response->getStatusCode();
$body = json_decode($response->getBody()->getContents(), true);
$errorMessage = isset($body['error']) ? $body['error'] : "Unknown error";
if ($statusCode == 429) {
throw new Exception("Rate limit exceeded. Please try again later.");
} elseif ($statusCode == 401) {
throw new Exception("Invalid API token. Please check your credentials.");
} else {
throw new Exception("API Error (" . $statusCode . "): " . $errorMessage);
}
} catch (ServerException $e) {
// 5xx errors
throw new Exception("Server error. Please try again later.");
} catch (ConnectException $e) {
// Connection errors
throw new Exception("Connection error: " . $e->getMessage());
} catch (Exception $e) {
// Other errors
throw new Exception("Error: " . $e->getMessage());
}
}
// Usage example is the same as the previous examples
?>
Working with the Response
The API returns a JSON response with detailed information about the email:
<?php
[
'email' => '[email protected]',
'result' => 'valid', // or 'invalid', 'risky', 'unknown'
'reason' => null, // reason for invalid or risky result
'role' => false, // true for role-based emails like "admin@" or "support@"
'free' => false, // true for free email providers like Gmail or Yahoo
'disposable' => false, // true for temporary/disposable email addresses
'accept_all' => false, // true if the domain accepts all emails
'did_you_mean' => null, // suggestion for misspelled emails
'domain' => 'techcorp.com',
'user' => 'alex',
'success' => true,
'domain_insight' => [
'category' => 'organization',
'name' => 'TechCorp Inc.',
'industry' => 'Software Development',
'country' => 'US',
'ticker' => 'TCH',
'employees' => 3500,
'description' => 'TechCorp Inc. is a leading software development company...'
]
]
?>
Handling Common Results
Here’s a utility function to process verification results:
<?php
/**
* Process a verification result and return a more user-friendly status
*
* @param array $result The API response
* @return array A simplified status array
*/
function handleVerificationResult($result) {
switch ($result['result']) {
case 'valid':
return [
'valid' => true,
'message' => 'Email address is valid and deliverable',
'details' => $result
];
case 'invalid':
return [
'valid' => false,
'message' => 'Email address is invalid: ' . ($result['reason'] ?? 'Unknown reason'),
'details' => $result
];
case 'risky':
return [
'valid' => false,
'risky' => true,
'message' => 'Email address is risky: ' . ($result['reason'] ?? 'Unknown reason'),
'details' => $result
];
case 'unknown':
return [
'valid' => null,
'message' => 'Verification result is inconclusive',
'details' => $result
];
default:
return [
'valid' => null,
'message' => 'Unknown verification result',
'details' => $result
];
}
}
// Example usage
try {
$result = verifyEmail('[email protected]');
$status = handleVerificationResult($result);
echo $status['message'] . "\n";
// You can also access domain intelligence
if (isset($status['details']['domain_insight'])) {
$insight = $status['details']['domain_insight'];
if (isset($insight['name'])) {
echo "Organization: " . $insight['name'] . "\n";
}
if (isset($insight['industry'])) {
echo "Industry: " . $insight['industry'] . "\n";
}
}
} catch (Exception $e) {
echo "Error: " . $e->getMessage() . "\n";
}
?>
Laravel Integration
Here’s how to integrate email verification into a Laravel application:
1. Create a Service Class
<?php
// app/Services/EmailVerificationService.php
namespace App\Services;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;
use Exception;
class EmailVerificationService
{
protected $apiToken;
protected $baseUrl;
public function __construct()
{
$this->apiToken = config('services.fuego.api_token');
$this->baseUrl = 'https://app.fuegoverify.com/api/v1';
}
/**
* Verify an email address
*
* @param string $email The email to verify
* @return array The verification result
*/
public function verify($email)
{
try {
$response = Http::timeout(30)
->get("{$this->baseUrl}/verify", [
'email' => $email,
'token' => $this->apiToken,
]);
if ($response->successful()) {
return $response->json();
}
if ($response->status() === 429) {
Log::warning('Fuego API rate limit exceeded');
throw new Exception('Rate limit exceeded. Please try again later.');
}
if ($response->status() === 401) {
Log::error('Fuego API authentication failed');
throw new Exception('Invalid API token. Please check your credentials.');
}
Log::error('Fuego API error', [
'status' => $response->status(),
'response' => $response->json(),
]);
throw new Exception('API error: ' . ($response->json('error') ?? 'Unknown error'));
} catch (Exception $e) {
Log::error('Email verification failed', [
'email' => $email,
'error' => $e->getMessage(),
]);
throw new Exception('Verification failed: ' . $e->getMessage());
}
}
/**
* Check if an email is valid
*
* @param string $email The email to check
* @return bool Whether the email is valid
*/
public function isValid($email)
{
try {
$result = $this->verify($email);
return $result['result'] === 'valid';
} catch (Exception $e) {
return false;
}
}
/**
* Handle verification result
*
* @param array $result The API response
* @return array A simplified status array
*/
public function handleResult($result)
{
switch ($result['result']) {
case 'valid':
return ['valid' => true, 'message' => 'Email is valid'];
case 'invalid':
return ['valid' => false, 'message' => 'Email is invalid: ' . ($result['reason'] ?? 'Unknown')];
case 'risky':
return ['valid' => false, 'risky' => true, 'message' => 'Email is risky: ' . ($result['reason'] ?? 'Unknown')];
default:
return ['valid' => false, 'message' => 'Email verification failed'];
}
}
}
2. Configure the API Key
Add your Fuego API key to your .env file:
FUEGO_API_TOKEN=your-api-token
And update your config/services.php file:
'fuego' => [
'api_token' => env('FUEGO_API_TOKEN'),
],
3. Create a Custom Validation Rule
<?php
// app/Rules/ValidEmail.php
namespace App\Rules;
use Illuminate\Contracts\Validation\Rule;
use App\Services\EmailVerificationService;
use Illuminate\Support\Facades\Cache;
class ValidEmail implements Rule
{
protected $message;
/**
* Determine if the validation rule passes.
*
* @param string $attribute
* @param mixed $value
* @return bool
*/
public function passes($attribute, $value)
{
// Skip validation for empty values
if (empty($value)) {
return true;
}
// Skip API validation in testing environment
if (app()->environment('testing')) {
return true;
}
// Check cache first to avoid unnecessary API calls
$cacheKey = 'email_validation:' . $value;
if (Cache::has($cacheKey)) {
$cachedResult = Cache::get($cacheKey);
$this->message = $cachedResult['message'] ?? null;
return $cachedResult['valid'] ?? false;
}
try {
$service = app(EmailVerificationService::class);
$result = $service->verify($value);
$status = $service->handleResult($result);
// Cache result for 1 day
Cache::put($cacheKey, $status, now()->addDay());
$this->message = $status['message'];
return $status['valid'];
} catch (\Exception $e) {
// Log the error but don't fail validation on API errors
\Log::error('Email validation error', ['email' => $value, 'error' => $e->getMessage()]);
return true;
}
}
/**
* Get the validation error message.
*
* @return string
*/
public function message()
{
return $this->message ?? 'The :attribute must be a valid deliverable email address.';
}
}
4. Use the Validation Rule
<?php
// In a controller or form request
use App\Rules\ValidEmail;
// In a controller
public function store(Request $request)
{
$request->validate([
'email' => ['required', 'email', new ValidEmail],
]);
// Process the form...
}
// Or in a form request
public function rules()
{
return [
'email' => ['required', 'email', new ValidEmail],
];
}
5. Create an API Controller for AJAX Validation
<?php
// app/Http/Controllers/Api/EmailVerificationController.php
namespace App\Http\Controllers\Api;
use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use App\Services\EmailVerificationService;
class EmailVerificationController extends Controller
{
protected $verificationService;
public function __construct(EmailVerificationService $verificationService)
{
$this->verificationService = $verificationService;
}
public function verify(Request $request)
{
$request->validate([
'email' => 'required|email',
]);
try {
$result = $this->verificationService->verify($request->email);
return response()->json($result);
} catch (\Exception $e) {
return response()->json([
'error' => $e->getMessage(),
], 422);
}
}
}
Add a route in routes/api.php:
Route::post('verify-email', 'Api\EmailVerificationController@verify');
6. JavaScript for Real-time Validation
<script>
document.addEventListener('DOMContentLoaded', function() {
const emailInput = document.getElementById('email');
const emailStatus = document.getElementById('email-status');
let debounceTimer;
emailInput.addEventListener('blur', function() {
const email = this.value;
if (!email || !email.includes('@')) {
return;
}
emailStatus.textContent = 'Verifying email...';
emailStatus.className = 'text-info';
clearTimeout(debounceTimer);
debounceTimer = setTimeout(function() {
fetch('/api/verify-email', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').getAttribute('content')
},
body: JSON.stringify({ email: email })
})
.then(response => response.json())
.then(data => {
if (data.error) {
emailStatus.textContent = 'Verification failed';
emailStatus.className = 'text-danger';
return;
}
if (data.result === 'valid') {
emailStatus.textContent = 'âś“ Email is valid';
emailStatus.className = 'text-success';
} else if (data.result === 'risky') {
emailStatus.textContent = `⚠️ ${data.reason || 'Email is risky'}`;
emailStatus.className = 'text-warning';
} else {
emailStatus.textContent = `âś— ${data.reason || 'Email is invalid'}`;
emailStatus.className = 'text-danger';
}
if (data.did_you_mean) {
emailStatus.textContent += ` - Did you mean ${data.did_you_mean}?`;
}
})
.catch(error => {
emailStatus.textContent = 'Verification failed';
emailStatus.className = 'text-danger';
console.error('Error:', error);
});
}, 500);
});
});
</script>
WordPress Integration
Here’s how to integrate email verification into a WordPress plugin or theme:
<?php
/**
* Function to verify an email using the Fuego API
*
* @param string $email The email to verify
* @return array|WP_Error The verification result or error
*/
function fuego_verify_email($email) {
$api_token = get_option('fuego_api_token');
if (empty($api_token)) {
return new WP_Error('no_api_token', 'No API token configured');
}
$url = add_query_arg([
'email' => urlencode($email),
'token' => urlencode($api_token),
], 'https://app.fuegoverify.com/api/v1/verify');
$response = wp_remote_get($url, [
'timeout' => 30,
'headers' => [
'Content-Type' => 'application/json',
],
]);
if (is_wp_error($response)) {
return $response;
}
$status_code = wp_remote_retrieve_response_code($response);
$body = wp_remote_retrieve_body($response);
$result = json_decode($body, true);
if ($status_code >= 400) {
$error_message = isset($result['error']) ? $result['error'] : 'Unknown error';
if ($status_code == 429) {
return new WP_Error('rate_limit', 'Rate limit exceeded. Please try again later.');
} elseif ($status_code == 401) {
return new WP_Error('invalid_token', 'Invalid API token. Please check your credentials.');
} else {
return new WP_Error('api_error', 'API Error (' . $status_code . '): ' . $error_message);
}
}
if (!$result) {
return new WP_Error('parse_error', 'Failed to parse API response');
}
return $result;
}
/**
* Validate email on comment submission
*/
function fuego_validate_comment_email($commentdata) {
$email = $commentdata['comment_author_email'];
// Skip validation for logged-in users or empty emails
if (is_user_logged_in() || empty($email)) {
return $commentdata;
}
// Check cache
$cache_key = 'fuego_email_validation_' . md5($email);
$cached = get_transient($cache_key);
if ($cached !== false) {
if (!$cached['valid']) {
wp_die(__('Sorry, that email address appears to be invalid.'));
}
return $commentdata;
}
// Verify the email
$result = fuego_verify_email($email);
if (is_wp_error($result)) {
// Log error but allow comment
error_log('Fuego email validation error: ' . $result->get_error_message());
return $commentdata;
}
// Process result
$valid = ($result['result'] === 'valid');
// Cache result (valid emails for 1 day, invalid for 1 hour)
set_transient(
$cache_key,
['valid' => $valid, 'result' => $result],
$valid ? DAY_IN_SECONDS : HOUR_IN_SECONDS
);
// Block invalid emails
if (!$valid) {
wp_die(__('Sorry, that email address appears to be invalid or risky. Please use a different email address.'));
}
return $commentdata;
}
add_filter('preprocess_comment', 'fuego_validate_comment_email');
/**
* Add settings page for API key
*/
function fuego_register_settings() {
add_options_page(
'Fuego Email Verification',
'Email Verification',
'manage_options',
'fuego-email-verification',
'fuego_settings_page'
);
register_setting('fuego_settings', 'fuego_api_token');
}
add_action('admin_menu', 'fuego_register_settings');
/**
* Settings page callback
*/
function fuego_settings_page() {
?>
<div class="wrap">
<h1>Fuego Email Verification Settings</h1>
<form method="post" action="options.php">
<?php settings_fields('fuego_settings'); ?>
<?php do_settings_sections('fuego_settings'); ?>
<table class="form-table">
<tr valign="top">
<th scope="row">API Token</th>
<td>
<input type="text" name="fuego_api_token" value="<?php echo esc_attr(get_option('fuego_api_token')); ?>" class="regular-text" />
<p class="description">Enter your Fuego API token. <a href="https://fuegoverify.com/api-verification" target="_blank">Get a token</a>.</p>
</td>
</tr>
</table>
<?php submit_button(); ?>
</form>
</div>
<?php
}
Rate Limiting and Error Handling
The API has rate limits to ensure fair usage. Here’s an implementation with exponential backoff retry logic:
<?php
/**
* Verify an email with retry logic for rate limits
*
* @param string $email The email to verify
* @param int $maxRetries Maximum number of retries
* @param float $baseDelay Base delay in seconds
* @return array The verification result
*/
function verifyEmailWithRetry($email, $maxRetries = 3, $baseDelay = 1.0) {
$retries = 0;
while ($retries <= $maxRetries) {
try {
return verifyEmail($email);
} catch (Exception $e) {
$error = strtolower($e->getMessage());
if (strpos($error, 'rate limit') !== false && $retries < $maxRetries) {
$retries++;
// Exponential backoff with jitter
$delay = $baseDelay * pow(2, $retries) + (mt_rand() / mt_getrandmax() * 0.5);
echo "Rate limited, retrying in {$delay}s (attempt {$retries}/{$maxRetries})\n";
sleep((int)$delay);
usleep(($delay - (int)$delay) * 1000000); // For fractional seconds
} else {
// Not a rate limit error or max retries reached
throw $e;
}
}
}
throw new Exception("Failed after {$maxRetries} retries");
}
Batch Processing
For processing large lists of emails:
<?php
/**
* Process a batch of emails with controlled rate limiting
*
* @param array $emails List of email addresses
* @param float $delay Delay between requests in seconds
* @return array Results indexed by email
*/
function verifyEmailBatch($emails, $delay = 0.2) {
$results = [];
foreach ($emails as $email) {
try {
echo "Verifying {$email}...\n";
$results[$email] = verifyEmailWithRetry($email);
// Add delay between requests to respect rate limits
usleep($delay * 1000000);
} catch (Exception $e) {
$results[$email] = [
'result' => 'error',
'reason' => $e->getMessage(),
];
echo "Error for {$email}: " . $e->getMessage() . "\n";
}
}
return $results;
}
/**
* Process a CSV file of emails
*
* @param string $inputFile Path to input CSV file
* @param string $outputFile Path to output CSV file
* @return void
*/
function processCsvFile($inputFile, $outputFile) {
// Read emails from CSV
$emails = [];
if (($handle = fopen($inputFile, "r")) !== false) {
while (($data = fgetcsv($handle)) !== false) {
if (isset($data[0]) && filter_var($data[0], FILTER_VALIDATE_EMAIL)) {
$emails[] = $data[0];
}
}
fclose($handle);
}
echo "Processing " . count($emails) . " emails...\n";
// Verify emails
$results = verifyEmailBatch($emails);
// Write results to CSV
if (($handle = fopen($outputFile, "w")) !== false) {
// Write header
fputcsv($handle, ['Email', 'Result', 'Reason', 'Company', 'Industry', 'Employees', 'Country']);
// Write data
foreach ($results as $email => $result) {
$company = $industry = $employees = $country = '';
if (isset($result['domain_insight'])) {
$company = $result['domain_insight']['name'] ?? '';
$industry = $result['domain_insight']['industry'] ?? '';
$employees = $result['domain_insight']['employees'] ?? '';
$country = $result['domain_insight']['country'] ?? '';
}
fputcsv($handle, [
$email,
$result['result'] ?? 'error',
$result['reason'] ?? '',
$company,
$industry,
$employees,
$country,
]);
}
fclose($handle);
}
echo "Results written to {$outputFile}\n";
}
// Usage
// processCsvFile('emails.csv', 'verification_results.csv');
?>
Conclusion
You now have all the tools you need to integrate the Fuego Email Verification API into your PHP applications. This integration will help ensure that your email data is valid and deliverable, improving your email campaigns and user data quality.
For more information and advanced usage, refer to the complete API documentation.
Pricing
For information about pricing, see our pricing page where you can calculate the exact cost for your email verification needs.