API Test Mode

Fuego provides a convenient test mode for developers to test their API integrations without consuming credits or affecting real verification data. Test mode is only available with development API keys, allowing you to simulate different verification scenarios during development and testing.

How to Use Test Mode

To use test mode, include the test_mode parameter in your API requests along with your development API key:

GET https://app.fuegoverify.com/api/v1/[email protected]&token=YOUR_DEV_API_KEY&test_mode=MODE

Replace MODE with one of the available test modes described below.

Available Test Modes

Fuego offers several predefined test modes to simulate different verification scenarios:

Test Mode	Description
`valid`	Simulates a valid, deliverable email
`invalid`	Simulates an invalid, undeliverable email
`risky`	Simulates a risky email (accept-all domain)
`error`	Simulates a verification error or timeout
`random`	Generates random results based on the valid ratio

Example Requests

# Test a valid email
curl -X GET "https://app.fuegoverify.com/api/v1/[email protected]&token=YOUR_DEV_API_KEY&test_mode=valid"

# Test an invalid email
curl -X GET "https://app.fuegoverify.com/api/v1/[email protected]&token=YOUR_DEV_API_KEY&test_mode=invalid"

# Test a risky email
curl -X GET "https://app.fuegoverify.com/api/v1/[email protected]&token=YOUR_DEV_API_KEY&test_mode=risky"

# Test an error scenario
curl -X GET "https://app.fuegoverify.com/api/v1/[email protected]&token=YOUR_DEV_API_KEY&test_mode=error"

# Test with random results
curl -X GET "https://app.fuegoverify.com/api/v1/[email protected]&token=YOUR_DEV_API_KEY&test_mode=random&valid_ratio=80"

Response Details

Each test mode returns a standardized response that matches what you’d receive in production:

Valid (`test_mode=valid`)

Simulates a deliverable email:

{
  "email": "[email protected]",
  "result": "deliverable",
  "reason": "accepted_email",
  "role": false,
  "cached": true,
  "free": false,
  "disposable": false,
  "accept_all": false,
  "did_you_mean": null,
  "domain": "jmc.com",
  "user": "rimmer",
  "success": true,
  "domain_insight": {
    "category": "organization",
    "name": "Jupiter Mining Corporation",
    "industry": "Mining",
    "country": "UK",
    "ticker": "JMC",
    "employees": 58000,
    "description": "Jupiter Mining Corporation is a large mining conglomerate that operates throughout the solar system, specializing in mineral extraction and deep space exploration."
  }
}

Invalid (`test_mode=invalid`)

Simulates an undeliverable email:

{
  "email": "[email protected]",
  "result": "undeliverable",
  "reason": "rejected_email",
  "role": false,
  "cached": true,
  "free": false,
  "disposable": false,
  "accept_all": false,
  "did_you_mean": null,
  "domain": "jmc.com",
  "user": "kochanski",
  "success": true,
  "domain_insight": {
    "category": "organization",
    "name": "Jupiter Mining Corporation",
    "industry": "Mining",
    "country": "UK",
    "ticker": "JMC",
    "employees": 58000,
    "description": "Jupiter Mining Corporation is a large mining conglomerate that operates throughout the solar system, specializing in mineral extraction and deep space exploration."
  }
}

Risky (`test_mode=risky`)

Simulates a risky email with an accept-all domain:

{
  "email": "[email protected]",
  "result": "risky",
  "reason": "low_deliverability",
  "role": false,
  "cached": true,
  "free": false,
  "disposable": false,
  "accept_all": true,
  "did_you_mean": null,
  "domain": "jmc.com",
  "user": "lister",
  "success": true,
  "domain_insight": {
    "category": "organization",
    "name": "Jupiter Mining Corporation",
    "industry": "Mining",
    "country": "UK",
    "ticker": "JMC",
    "employees": 58000,
    "description": "Jupiter Mining Corporation is a large mining conglomerate that operates throughout the solar system, specializing in mineral extraction and deep space exploration."
  }
}

Error (`test_mode=error`)

Simulates a verification failure:

{
  "email": "[email protected]",
  "result": "unknown",
  "reason": "timeout",
  "role": false,
  "cached": true,
  "free": false,
  "disposable": false,
  "accept_all": false,
  "did_you_mean": null,
  "domain": "jmc.com",
  "user": "holly",
  "success": true,
  "domain_insight": {
    "category": "organization",
    "name": "Jupiter Mining Corporation",
    "industry": "Mining",
    "country": "UK",
    "ticker": "JMC",
    "employees": 58000,
    "description": "Jupiter Mining Corporation is a large mining conglomerate that operates throughout the solar system, specializing in mineral extraction and deep space exploration."
  }
}

Random (`test_mode=random`)

Generates random verification results based on the specified valid ratio:

{
  "email": "[email protected]",
  "result": "[random result]",
  "reason": "[corresponding reason]",
  "role": true/false,
  "cached": true,
  "free": true/false,
  "disposable": true/false,
  "accept_all": true/false,
  "did_you_mean": null,
  "domain": "jmc.com",
  "user": "cat",
  "success": true,
  "domain_insight": {
    "category": "organization",
    "name": "Jupiter Mining Corporation",
    "industry": "Mining",
    "country": "UK",
    "ticker": "JMC",
    "employees": 58000,
    "description": "Jupiter Mining Corporation is a large mining conglomerate that operates throughout the solar system, specializing in mineral extraction and deep space exploration."
  }
}

Valid Ratio Parameter

When using the random test mode, you can control the likelihood of different results with the valid_ratio parameter:

GET https://app.fuegoverify.com/api/v1/[email protected]&token=YOUR_DEV_API_KEY&test_mode=random&valid_ratio=80

The valid_ratio parameter accepts a number between 0 and 100:

Higher values (e.g., 90) will produce more “deliverable” results
Lower values (e.g., 20) will produce more “undeliverable” and “risky” results
Default is 80 if not specified

Important Notes

Test mode is only available with development API keys
Production API keys will ignore the test_mode parameter and perform actual verifications
Test mode does not consume verification credits
Test mode does not affect your verification statistics or reports
Test mode responses are clearly marked as cached to indicate they are simulated
Test responses include realistic domain insights similar to production results

Integration Examples

JavaScript

async function testEmailVerification(email, testMode = 'valid', validRatio = 80) {
  const params = new URLSearchParams({
    token: "YOUR_DEV_API_KEY",
    email: email,
    test_mode: testMode
  });
  
  if (testMode === 'random') {
    params.append("valid_ratio", validRatio);
  }
  
  const response = await fetch(`https://app.fuegoverify.com/api/v1/verify?${params.toString()}`);
  const data = await response.json();
  return data;
}

// Example usage:
testEmailVerification('[email protected]', 'valid')
  .then(result => console.log(result))
  .catch(error => console.error(error));

Python

import requests

def test_email_verification(email, test_mode='valid', valid_ratio=80):
    params = {
        "token": "YOUR_DEV_API_KEY", 
        "email": email,
        "test_mode": test_mode
    }
    
    if test_mode == 'random':
        params["valid_ratio"] = valid_ratio
        
    response = requests.get(
        "https://app.fuegoverify.com/api/v1/verify",
        params=params
    )
    return response.json()

# Example usage:
result = test_email_verification('[email protected]', 'valid')
print(result)

Ruby

require 'net/http'
require 'json'
require 'uri'

def test_email_verification(email, test_mode = 'valid', valid_ratio = 80)
  uri = URI("https://app.fuegoverify.com/api/v1/verify")
  params = { 
    token: "YOUR_DEV_API_KEY", 
    email: email,
    test_mode: test_mode
  }
  
  params[:valid_ratio] = valid_ratio if test_mode == 'random'
  
  uri.query = URI.encode_www_form(params)
  
  response = Net::HTTP.get(uri)
  JSON.parse(response)
end

# Example usage:
result = test_email_verification('[email protected]', 'error')
puts result

Best Practices

Use test mode during development and testing, then switch to production API keys for live environments
Test all possible verification results (valid, invalid, risky, error) to ensure your application handles them properly
Implement proper error handling in your integration
Use the random test mode with different valid_ratio values to test how your application handles varying distributions of results
Consider using environment variables to manage different API keys between development and production environments

API Test Mode

API Test Mode

How to Use Test Mode

Available Test Modes

Example Requests

Response Details

Valid (test_mode=valid)

Invalid (test_mode=invalid)

Risky (test_mode=risky)

Error (test_mode=error)

Random (test_mode=random)

Valid Ratio Parameter

Important Notes

Integration Examples

JavaScript

Python

Ruby

Best Practices

Valid (`test_mode=valid`)

Invalid (`test_mode=invalid`)

Risky (`test_mode=risky`)

Error (`test_mode=error`)

Random (`test_mode=random`)