API Documentation

Everything you need to integrate EmailFinder into your application.

Authentication

All API requests require an API key passed in the X-API-Key header.

Header
X-API-Key: your-api-key-here

You can generate API keys from the dashboard. Free tier keys are rate-limited to 50 requests per month.

Base URL

https://emailfinder-api.buildkit.store

For self-hosted instances, replace with your own server URL (default: http://localhost:8000).

Try It Now

Run this command in your terminal to see the API in action -- no API key required for the health check, or use the demo key for a quick lookup.

Health check (no auth needed)
curl https://emailfinder-api.buildkit.store/health
Quick email lookup (demo key)
curl -X POST https://emailfinder-api.buildkit.store/find \
  -H "Content-Type: application/json" \
  -H "X-API-Key: buildkit-emailfinder-2026" \
  -d '{"url": "https://stripe.com"}'

POST /find

Find email addresses for a given business URL.

Request Body

JSON
{
  "url": "https://acmecorp.com",
  "name": "Acme Corp",           // optional
  "deep_scan": true,             // optional, default: false
  "verify_smtp": true            // optional, default: true
}

Response

JSON
{
  "success": true,
  "domain": "acmecorp.com",
  "emails": [
    {
      "email": "john@acmecorp.com",
      "confidence": 95,
      "source": "website_scrape",
      "verified": true,
      "mx_valid": true
    },
    {
      "email": "sales@acmecorp.com",
      "confidence": 88,
      "source": "pattern_detection",
      "verified": true,
      "mx_valid": true
    }
  ],
  "meta": {
    "scan_time_ms": 2340,
    "methods_used": ["scrape", "pattern", "smtp"],
    "cached": false
  }
}

Code Examples

curl
curl -X POST https://emailfinder-api.buildkit.store/find \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"url": "https://acmecorp.com", "verify_smtp": true}'
Python
import requests

response = requests.post(
    "https://emailfinder-api.buildkit.store/find",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "your-api-key",
    },
    json={
        "url": "https://acmecorp.com",
        "verify_smtp": True,
    },
)

data = response.json()
for email in data["emails"]:
    print(f"{email['email']} (confidence: {email['confidence']}%)")
JavaScript
const response = await fetch(
  "https://emailfinder-api.buildkit.store/find",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": "your-api-key",
    },
    body: JSON.stringify({
      url: "https://acmecorp.com",
      verify_smtp: true,
    }),
  }
);

const data = await response.json();
data.emails.forEach((email) => {
  console.log(`${email.email} (confidence: ${email.confidence}%)`);
});

POST /find/batch

Find emails for multiple URLs in a single request. Pro and Business plans only.

Request Body

JSON
{
  "urls": [
    "https://acmecorp.com",
    "https://example.com",
    "https://startup.io"
  ],
  "verify_smtp": true
}

Response

JSON
{
  "success": true,
  "results": [
    {
      "domain": "acmecorp.com",
      "emails": [...],
      "meta": { ... }
    },
    {
      "domain": "example.com",
      "emails": [...],
      "meta": { ... }
    }
  ],
  "total_emails_found": 7,
  "total_scan_time_ms": 5420
}

GET /health

Health check endpoint. No authentication required.

Response
{
  "status": "ok",
  "version": "1.0.0",
  "uptime_seconds": 86400
}

GET /cache/stats

View cache statistics for your API key.

Response
{
  "total_cached": 142,
  "cache_hit_rate": 0.34,
  "oldest_entry": "2026-03-01T10:00:00Z",
  "storage_used_mb": 2.4
}

Rate Limits

PlanMonthly LookupsRequests/MinuteBatch Size
Free505--
Pro1,0003050
Business5,00060500

Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset.