EasyEmailFinder API

Programmatic access to business search, email enrichment, and lead generation.

Base URL: https://easyemailfinder.com/api/v1

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from the Developer Dashboard.

curl https://easyemailfinder.com/api/v1/balance \
  -H "Authorization: Bearer eef_live_your_key_here"

API keys are shown only once at creation. Store them securely. Never expose keys in client-side code.

Rate Limits

Standard endpoints

120 req/min

Search, balance, usage

Enrich endpoints

30 req/min

Enrich, batch enrich, search+enrich

When rate limited, the response includes a Retry-After header with the number of seconds to wait.

Endpoints

POST/api/v1/search

Search for businesses by query. Returns names, addresses, phone numbers, and websites — but no emails. Use the enrich endpoint to get emails. Set mode to "digital" to search for online-only businesses (SaaS, agencies, etc.) instead of local businesses.

Cost: FreeRate limit: 120/min

Request body:

{
  "query": "dentists in denver",
  "pageToken": null,
  "mode": "local"          // "local" (default) or "digital"
}

Response:

{
  "data": {
    "businesses": [
      {
        "placeId": "ChIJ...",
        "name": "Denver Family Dentistry",
        "address": "123 Main St, Denver, CO",
        "phone": "(303) 555-0100",
        "website": "https://denverfamilydentistry.com",
        "rating": 4.8,
        "userRatingCount": 245,
        "primaryType": "dentist",
        "types": ["dentist", "health"]
      }
    ],
    "nextPageToken": "abc123...",
    "totalReturned": 20
  },
  "meta": { "requestId": "req_a1b2c3", "creditsUsed": 0 }
}

POST/api/v1/enrich

Scrape a website for email addresses, tech stack info, and social media links. Only charged if emails are found — no charge when no emails are returned.

Cost: 1 credit per email foundRate limit: 300/min

Request body:

{
  "website": "https://denverfamilydentistry.com"
}

Response:

{
  "data": {
    "website": "https://denverfamilydentistry.com",
    "emails": ["info@denverfamilydentistry.com"],
    "techStack": "wordpress",
    "socialLinks": {
      "facebook": "https://facebook.com/dfdenver",
      "instagram": "https://instagram.com/dfdenver"
    },
    "pagesScraped": 5
  },
  "meta": {
    "requestId": "req_d4e5f6",
    "creditsUsed": 1,
    "remainingCredits": 94.75
  }
}

POST/api/v1/enrich-batch

Enrich up to 20 websites in one request. Credits are deducted upfront for all websites.

Cost: 1 credit per websiteRate limit: 300/min

Request body:

{
  "websites": [
    "https://denverfamilydentistry.com",
    "https://example-plumber.com"
  ]
}

Response:

{
  "data": {
    "results": [
      {
        "website": "https://denverfamilydentistry.com",
        "emails": ["info@denverfamilydentistry.com"],
        "techStack": "wordpress",
        "socialLinks": {},
        "pagesScraped": 5
      }
    ]
  },
  "meta": {
    "requestId": "req_g7h8i9",
    "creditsUsed": 2,
    "remainingCredits": 92.75
  }
}

POST/api/v1/search-and-enrich

Combined endpoint: search for businesses and enrich their websites in one call. Only businesses with websites are enriched. Credits are only charged for results where emails are found. Set mode to "digital" to search for online-only businesses.

Cost: 1 credit per result with emailRate limit: 300/min

Request body:

{
  "query": "dentists in denver",
  "limit": 20,
  "mode": "local"          // "local" (default) or "digital"
}

Response:

{
  "data": {
    "results": [
      {
        "placeId": "ChIJ...",
        "name": "Denver Family Dentistry",
        "address": "123 Main St, Denver, CO",
        "website": "https://denverfamilydentistry.com",
        "emails": ["info@denverfamilydentistry.com"],
        "techStack": "wordpress",
        "socialLinks": {}
      }
    ],
    "query": "dentists in denver",
    "totalReturned": 20
  },
  "meta": {
    "requestId": "req_j0k1l2",
    "creditsUsed": 20,
    "remainingCredits": 72.75
  }
}

GET/api/v1/balance

Check your current credit balance.

Cost: FreeRate limit: 120/min

Response:

{
  "data": {
    "credits": 94.75,
    "emailCredits": 379,
    "costPerEmail": 0.25
  },
  "meta": {
    "requestId": "req_m3n4o5",
    "remainingCredits": 94.75
  }
}

GET/api/v1/usage?days=7

View API usage breakdown by day.

Cost: FreeRate limit: 120/min

Response:

{
  "data": {
    "days": 7,
    "totalCreditsUsed": 25.5,
    "totalRequests": 102,
    "daily": [
      { "date": "2026-02-20", "credits": 5.0, "requests": 20 },
      { "date": "2026-02-21", "credits": 8.25, "requests": 33 }
    ]
  },
  "meta": { "requestId": "req_p6q7r8" }
}

Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Missing, invalid, or revoked API key
`RATE_LIMITED`	429	Too many requests. Check Retry-After header.
`INSUFFICIENT_CREDITS`	402	Not enough credits. Purchase more at /developer.
`INVALID_REQUEST`	400	Missing or invalid request parameters
`INTERNAL_ERROR`	500	Unexpected server error

All errors follow this format:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits. 1 credit required per enrichment."
  },
  "meta": { "requestId": "req_abc123" }
}

Credit Costs

Endpoint	Cost	Notes
/v1/search	Free	Search is the funnel top
/v1/enrich	1 credit	Per website with email found. No charge if no emails returned.
/v1/enrich-batch	1 credit/website	Max 20 per batch, deducted upfront
/v1/search-and-enrich	1 credit/result with email	Max 60 results. Only charged for results where emails are found.
/v1/balance	Free
/v1/usage	Free

Purchase credits from the Developer Dashboard or the main app. Credits are shared between the app and the API.

Billing Behavior

Pay-per-email-found model

Credits are only deducted when emails are actually found. If an enrichment returns 0 emails, you are not charged. This applies to both the /v1/enrich and /v1/search-and-enrich endpoints.

Rules per endpoint:

Endpoint	When charged	When NOT charged
`/v1/search`	Never (free)	Always free
`/v1/enrich`	1 credit when `data.emails.length > 0`	0 credits when `data.emails` is empty
`/v1/search-and-enrich`	1 credit per result where `emails.length > 0`	Results with 0 emails are not charged
`/v1/balance`, `/v1/usage`	Never (free)	Always free

Using meta.creditsUsed

Every response includes meta.creditsUsed and meta.remainingCredits. Always use these as the source of truth for billing — do not calculate credits client-side.

// Example: enrich with no emails found
{
  "data": {
    "website": "https://example.com",
    "emails": [],
    "techStack": "wordpress",
    "socialLinks": {},
    "pagesScraped": 3
  },
  "meta": {
    "requestId": "req_abc123",
    "creditsUsed": 0,
    "remainingCredits": 50.0
  }
}

// Example: enrich with emails found
{
  "data": {
    "website": "https://example.com",
    "emails": ["info@example.com"],
    "techStack": "wordpress",
    "socialLinks": {},
    "pagesScraped": 3
  },
  "meta": {
    "requestId": "req_def456",
    "creditsUsed": 1,
    "remainingCredits": 49.0
  }
}

Building a GUI on top of this API

If you are building a frontend that wraps this API, follow these guidelines:

Show credit estimates as "up to X credits" — actual cost depends on how many results return emails.
After each API call, read meta.creditsUsed and meta.remainingCredits to update your UI.
For search-and-enrich results tables, you can distinguish charged vs. free rows by checking whether emails.length > 0 on each result.
Do not pre-deduct or estimate credits locally — the API response is authoritative.

OpenClaw Integration

OpenClaw Compatible

Easy Email Finder ships with an OpenClaw skill, so AI agents running on OpenClaw can search for businesses and enrich them with emails using your API key.

Install the skill:

# Copy into your OpenClaw skills directory
cp -r openclaw-skill/  ~/.openclaw/skills/easy-email-finder/

Configure your API key:

// ~/.openclaw/openclaw.json
{
  "skills": {
    "entries": {
      "easy-email-finder": {
        "enabled": true,
        "apiKey": "eef_live_your_key_here"
      }
    }
  }
}

Once installed, your OpenClaw agent can use natural language like "find dentists in Denver and get their emails" and it will call the API endpoints automatically.