Enrichment API

The Fuego API enriches email addresses in real-time directly from your application. It is fast enough to run at the point of capture — during user signup, lead capture, or form submission — and tells you who is behind the address, what kind of organization it belongs to, and whether it shows abuse signals.

Fuego never connects to mail servers. All domain checks are DNS-only.

API Basics

• Base URL: https://app.gofuego.io/api/v1/
• Authentication: API token via the token query parameter (required for all requests)
• Rate Limit: by plan — 60/min (Starter), 300/min (Growth), 600/min (Scale); 30/min on the free trial
• Format: JSON

Authentication

Add your token as a query parameter to every request:

https://app.gofuego.io/api/v1/enrich?token=YOUR_API_TOKEN&email=kochanski@jmc.com

Keep your API token secure — never expose it in client-side code or public repositories.

Getting Started

1. Log in to your Fuego account at app.gofuego.io
2. Navigate to “API Settings” in your account dashboard
3. Generate a new API token
4. Use this token in your API requests as shown above

Enriching an Email

Endpoint

GET https://app.gofuego.io/api/v1/enrich

Parameters

Each request uses one enrichment from your monthly plan (or free-trial balance). Syntactically invalid addresses and unknown results (category: "unknown") are always free — you only pay when Fuego tells you something useful.

Example Request

curl -X GET "https://app.gofuego.io/api/v1/enrich?token=YOUR_API_TOKEN&email=kochanski@jmc.com"

Example Response

{
  "success": true,
  "email": "kochanski@jmc.com",
  "user": "kochanski",
  "domain": "jmc.com",
  "syntax_valid": true,
  "did_you_mean": null,
  "normalized_email": "kochanski@jmc.com",
  "disposable": false,
  "free": false,
  "role": false,
  "plus_address": false,
  "has_mx": true,
  "category": "enterprise",
  "risk": "low",
  "organization": {
    "name": "Jupiter Mining Corporation",
    "industry": "Mining (except Oil and Gas)",
    "country": "UK",
    "ticker": "JMC",
    "employees": 58000,
    "employee_range": "10000+",
    "description": "Jupiter Mining Corporation is a large mining company operating ore freighters across the solar system."
  }
}

Response Fields

Category Values

Risk Levels

Organization Fields

All organization fields are null when the value is unknown.

More Examples

A disposable address:

{
  "success": true,
  "email": "rimmer@trashmail.example",
  "user": "rimmer",
  "domain": "trashmail.example",
  "syntax_valid": true,
  "did_you_mean": null,
  "normalized_email": "rimmer@trashmail.example",
  "disposable": true,
  "free": false,
  "role": false,
  "plus_address": false,
  "has_mx": true,
  "category": "disposable",
  "risk": "high",
  "organization": {
    "name": null,
    "industry": null,
    "country": null,
    "ticker": null,
    "employees": null,
    "employee_range": null,
    "description": null
  }
}

An individual using plus addressing — note normalized_email gives you the canonical mailbox for deduplication:

{
  "success": true,
  "email": "lister+promo@gmail.com",
  "user": "lister+promo",
  "domain": "gmail.com",
  "syntax_valid": true,
  "did_you_mean": null,
  "normalized_email": "lister@gmail.com",
  "disposable": false,
  "free": true,
  "role": false,
  "plus_address": true,
  "has_mx": true,
  "category": "individual",
  "risk": "low",
  "organization": {
    "name": null,
    "industry": null,
    "country": null,
    "ticker": null,
    "employees": null,
    "employee_range": null,
    "description": null
  }
}

A likely typo — the mistyped domain has no MX records, and did_you_mean carries the suggested fix:

{
  "success": true,
  "email": "lister@gmail.cmo",
  "user": "lister",
  "domain": "gmail.cmo",
  "syntax_valid": true,
  "did_you_mean": "lister@gmail.com",
  "normalized_email": "lister@gmail.cmo",
  "disposable": false,
  "free": false,
  "role": false,
  "plus_address": false,
  "has_mx": false,
  "category": "unknown",
  "risk": "high",
  "organization": {
    "name": null,
    "industry": null,
    "country": null,
    "ticker": null,
    "employees": null,
    "employee_range": null,
    "description": null
  }
}

Bulk List Endpoints

You can also enrich whole CSV files through the API. See the List Enrichment guide for a walkthrough.

Upload a List

POST https://app.gofuego.io/api/v1/lists

Multipart form upload with a file field (your CSV) and an optional name field.

curl -X POST "https://app.gofuego.io/api/v1/lists?token=YOUR_API_TOKEN" \
  -F "file=@leads.csv" \
  -F "name=June signups"

Response (201 Created):

{
  "id": 42,
  "name": "June signups",
  "status": "analyzing",
  "message": "List successfully uploaded and queued for processing."
}

The list is analyzed automatically. Its status becomes ready_to_enrich once analysis completes.

Check List Status

GET https://app.gofuego.io/api/v1/lists/:id

{
  "id": 42,
  "name": "June signups",
  "status": "enriching",
  "progress": 65,
  "total_rows": 10000,
  "processed_rows": 6500,
  "stats": null
}

Statuses: uploaded, analyzing, ready_to_enrich, enriching, finalizing, completed, error.

Start Enrichment

POST https://app.gofuego.io/api/v1/lists/:id/enrich

Starts enrichment of a list in ready_to_enrich status. Uses one enrichment per row, charged against your monthly quota (or trial credits) up front — errored and invalid rows are refunded. Returns 402 Payment Required if your trial credits can’t cover the list and you have no subscription.

{
  "status": "enriching",
  "message": "Enrichment started."
}

Get Results

GET https://app.gofuego.io/api/v1/lists/:id/results

{
  "id": 42,
  "name": "June signups",
  "status": "completed",
  "stats": {
    "low_risk": 8900,
    "medium_risk": 700,
    "high_risk": 380,
    "error": 20,
    "categories": {
      "enterprise": 1200,
      "smb": 4400,
      "education": 300,
      "government": 100,
      "nonprofit": 150,
      "individual": 3300,
      "disposable": 250,
      "unknown": 300
    },
    "role": 700,
    "free": 3300,
    "disposable": 250,
    "plus_address": 45
  },
  "download_url": "https://app.gofuego.io/...",
  "completed_at": "2026-06-11T12:00:00Z"
}

Rows that error during enrichment (and syntactically invalid rows) are refunded automatically.

The enriched CSV contains your original columns plus: category, risk, syntax_valid, role, free, disposable, plus_address, has_mx, did_you_mean, organization_name, organization_industry, organization_country, organization_employees, organization_employee_range, organization_ticker.

Integration Examples

JavaScript

async function enrichEmail(email) {
  const params = new URLSearchParams({
    token: process.env.FUEGO_API_KEY,
    email: email
  });

  const response = await fetch(`https://app.gofuego.io/api/v1/enrich?${params.toString()}`);

  if (!response.ok) {
    throw new Error(`Fuego API error: ${response.status}`);
  }

  return response.json();
}

// Example usage in a signup flow:
const lead = await enrichEmail("kochanski@jmc.com");

if (lead.risk === "high") {
  // Block disposable, invalid, or no-MX signups
} else if (lead.did_you_mean) {
  // Ask the user: "Did you mean kochanski@jmc.com?"
} else if (lead.plus_address) {
  // Check lead.normalized_email against existing accounts
} else if (lead.category === "enterprise") {
  // Route to sales
}

Python

import os
import requests

def enrich_email(email):
    response = requests.get(
        "https://app.gofuego.io/api/v1/enrich",
        params={"token": os.environ["FUEGO_API_KEY"], "email": email},
    )
    response.raise_for_status()
    return response.json()

# Example usage in a signup flow:
lead = enrich_email("kochanski@jmc.com")

if lead["risk"] == "high":
    pass  # Block disposable, invalid, or no-MX signups
elif lead["did_you_mean"]:
    pass  # Ask the user: "Did you mean ...?"
elif lead["plus_address"]:
    pass  # Check lead["normalized_email"] against existing accounts
elif lead["category"] == "enterprise":
    pass  # Route to sales

Ruby

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

def enrich_email(email)
  uri = URI("https://app.gofuego.io/api/v1/enrich")
  uri.query = URI.encode_www_form(token: ENV["FUEGO_API_KEY"], email: email)

  response = Net::HTTP.get(uri)
  JSON.parse(response)
end

# Example usage in a signup flow:
lead = enrich_email("kochanski@jmc.com")

case
when lead["risk"] == "high"
  # Block disposable, invalid, or no-MX signups
when lead["did_you_mean"]
  # Ask the user: "Did you mean ...?"
when lead["plus_address"]
  # Check lead["normalized_email"] against existing accounts
when lead["category"] == "enterprise"
  # Route to sales
end

Error Handling

The API returns HTTP status codes to indicate success or failure:

Error Response Format

When an error occurs, the API returns a JSON response with details:

{
  "error": "Error message",
  "timestamp": "2026-06-11T12:00:00Z"
}

Note that a syntactically invalid email is not an error: the request succeeds with syntax_valid: false, risk: "high", and does not count against your quota.

Best Practices

• Store your API token securely and never expose it in client-side code
• Implement proper error handling and respect your plan’s rate limit
• Use test mode with a development API key while building your integration
• Surface did_you_mean suggestions to users instead of silently rejecting typos
• Deduplicate accounts on normalized_email so plus-address variants can’t create multiples
• Treat risk as your first gate, then branch on category for routing and segmentation

For more information on interpreting enrichment results, see our Understanding Enrichment Data guide.