Email Finder API

Read this field before you use an address. It is the whole point of the product, and the three values are not interchangeable.

Two further rules the mapper enforces, so you can rely on them: a domain flagged catch-all can never come back verified, and neither can a role account like info@ — a shared mailbox may well be live, but it is not the person you asked about. Anything we do not conclusively recognise falls through to unverified.

confidence is a 0–1 figure that is clamped by the status: an accept_all or unverified result can never present with the confidence of a confirmed one, regardless of any score the underlying check produced.

Mint a key at /dashboard/api-keys. Pass it as a bearer token, or as ?api_key= when your client cannot set headers (the Ounie AI Team's manual MCP entries, for instance).

Authorization: Bearer eml_live_...
# or
https://emailfinder.ounie.com/api/lookup?api_key=eml_live_...

Your ounie.com master key (ounie_live_…) also works here once you enable “Use across Ounie apps” in your ounie.com settings — one key for the whole fleet. Every call draws its owner's shared Ounie wallet and is refused rather than allowed to overdraw.

POST /api/lookup

Costs 10 credits when an address comes back, zero otherwise.

curl -X POST https://emailfinder.ounie.com/api/lookup \
  -H "Authorization: Bearer eml_live_..." \
  -H "content-type: application/json" \
  -d '{
    "firstName": "Dana",
    "lastName": "Whitfield",
    "domain": "northbeam.io",
    "companyName": "Northbeam"
  }'

companyName is optional and is stored as a label on the lookup for your own records; it does not influence the search. The search itself is driven entirely by domain.

Response

{
  "id": "0f3c…",
  "found": true,
  "email": "dana.whitfield@northbeam.io",
  "confidence": 0.92,
  "verification": "verified",
  "pattern": "first.last",
  "alternatives": [],
  "tested_count": 4,
  "flags": {
    "catch_all": false,
    "disposable": false,
    "role_account": false
  },
  "query": { "first_name": "Dana", "last_name": "Whitfield",
             "domain": "northbeam.io", "company_name": "Northbeam" },
  "credits_charged": 10
}

When nothing is found you get "found": false, "credits_charged": 0, and a note saying so.

alternatives carries other plausible addresses when the underlying check supplies them. It is frequently an empty array, and that is a real answer — we do not manufacture entries to make a response look fuller.

GET /api/lookups

Your history, newest first. Free. Optional ?domain=, ?limit=, ?offset=.

GET /api/lookups/{id}

One past lookup. Free.

GET /api/credits

Your spendable Ounie credits. Free.

GET /api/pricing

Public. Price, status meanings, and the x402 endpoint.

A Model Context Protocol server at https://emailfinder.ounie.com/api/mcp (Streamable HTTP) and https://emailfinder.ounie.com/api/sse. Works with Claude, Cursor, ChatGPT and the Ounie AI Team.

{
  "mcpServers": {
    "email-finder": {
      "url": "https://emailfinder.ounie.com/api/mcp",
      "headers": { "Authorization": "Bearer eml_live_..." }
    }
  }
}

For hosts that cannot set static headers — the Ounie AI Team's manual HTTP MCP entry among them — put the key in the URL instead: https://emailfinder.ounie.com/api/mcp?api_key=eml_live_…

Tools

• find_email10 cr on an answerfirst_name, last_name, domain, company_name?
• get_lookupfreelookup_id
• list_lookupsfreedomain?, limit?
• get_credit_balancefree—
• get_pricingfree · public—
• whoamifree—

If the wallet cannot cover a lookup the tool returns an insufficient_credits error with a link to top up. An agent is refused, never allowed to overdraw.

Keyless agents pay $0.12 in USDC on Base. POST without a payment header to receive the terms, sign, and retry with X-Payment.

POST https://emailfinder.ounie.com/api/x402/find
{ "first_name": "Dana", "last_name": "Whitfield",
  "domain": "northbeam.io" }

→ 402 Payment Required   (terms, payTo, USDC contract, EIP-712 domain)
→ retry with X-Payment: <signed authorization>
→ 200 { "found": true, "email": "...", "verification": "verified",
        "settled": true, "payment": { "tx_hash": "0x…" } }

Requests that cannot possibly succeed — a missing name, a malformed domain, a consumer mailbox provider, a disposable domain — are refused with a 4xx before any price is quoted. You will never be asked to sign a payment for work that was always going to fail.

Every 4xx in this table is decided from the request alone, so it costs nothing and behaves identically on the credit and x402 rails.

A lookup depends on a third-party discovery engine and on the behaviour of mail servers we do not control. We do not promise uptime, and we do not promise that any given person's address is findable.

What we do promise is how a bad day behaves. When the engine is unavailable, every rail returns 503 temporarily_unavailable — and it does so before reserving credits or quoting a price, so there is no reserve-then-refund cycle to reconcile and nothing for an agent to sign. Once the engine recovers, the next request goes through on its own; there is nothing to reset.

You are never charged for a lookup we could not run. If one does slip through and fail, the reservation refunds in full, automatically.

A scheduled probe checks the engine every few minutes. While it reports the engine as down, every rail refuses up front and charges nothing — there is no window in which a caller is let through to discover the outage the expensive way. When the probe succeeds again, service resumes on its own.

• · 5 concurrent lookups per account.
• · Up to 5 active API keys per account.
• · Roughly four address shapes tested per lookup: first.last, first, flast, f.last.
• · One named person at one named company per call.

A verified status tells you a mailbox exists. It does not tell you that contacting it is appropriate or lawful in your jurisdiction — that judgement, and compliance with the rules that apply to you, stays with you.