Find a Verified Work Email with Clay

POST /find-email (prospects: full_name, company_name, company_domain)
    ↓
POST /routines/{routine_id}/run   (Work Email, multi-provider waterfall)
    ↓
GET /routines/run/{run_id}/results (poll until complete -- this waterfall can take 30-60+ seconds)
    ↓
{ emails: [{ id, work_email }] }

Implement a Flask service that finds verified work emails for a list of
prospects using Clay's "Work Email" managed function.

Requirements:
- Base URL: https://api.clay.com/public/v0, auth header "clay-api-key".
- Find the real routine id for "Work Email" via your workspace's routine
  catalog before writing code that assumes a fixed id.
- Confirmed real input schema: {"Full Name": str, "Company Domain": hostname,
  "Company Name": str} (required); optional fields include Social Profile
  URL and Personal Email.
- Confirmed real result key: "Work Email" (a plain email string).
- This is a multi-provider waterfall -- it cascades across providers until
  one returns a valid result, so completion can take 30-60+ seconds per item.
  Poll with a generous interval and a generous total timeout; do not assume
  a fast response.
- If the routine returns no email for a given item, report null. Never
  synthesize a pattern-guessed address (e.g. [email protected]) as a
  fallback.
- Run the verification step below before finishing.

mkdir find-verified-work-email && cd find-verified-work-email
python -m venv venv && source venv/bin/activate
pip install flask requests

clay routines list | grep -A2 '"Work Email"'

clay routines get function:t_XXXXXXXXXXXXXXXXXXXX

CLAY_API_KEY=
CLAY_ROUTINE_ID_WORK_EMAIL=function:t_XXXXXXXXXXXXXXXXXXXX
POLL_INTERVAL_SECONDS=5
MAX_WAIT_SECONDS=180

"""
Work email finder for SDRs, backed by the Clay 'Work Email' routine.

POST /find-email
    {"prospects": [{"full_name", "company_name", "company_domain"}, ...]}
->  {"emails": [{"id", "work_email"}, ...]}

work_email is null whenever we could not obtain a real address. We never
synthesise a pattern-guessed address as a fallback. This is a multi-provider
waterfall, so completion routinely takes 30-60+ seconds per item -- the
poll loop below is intentionally patient.
"""

import os
import time

import requests
from flask import Flask, jsonify, request

app = Flask(__name__)

BASE_URL = "https://api.clay.com/public/v0"
HEADERS = {"clay-api-key": os.environ["CLAY_API_KEY"], "Content-Type": "application/json"}
ROUTINE_ID = os.environ["CLAY_ROUTINE_ID_WORK_EMAIL"]
POLL_INTERVAL = int(os.environ.get("POLL_INTERVAL_SECONDS", 5))
MAX_WAIT = int(os.environ.get("MAX_WAIT_SECONDS", 180))


def submit(prospects):
    items = [
        {
            "id": f"prospect-{i}",
            "inputs": {
                "Full Name": p["full_name"],
                "Company Domain": p["company_domain"],
                "Company Name": p["company_name"],
            },
        }
        for i, p in enumerate(prospects)
    ]
    resp = requests.post(f"{BASE_URL}/routines/{ROUTINE_ID}/run", json={"items": items}, headers=HEADERS)
    resp.raise_for_status()
    return resp.json()["routine_run_id"]


def poll(run_id):
    deadline = time.time() + MAX_WAIT
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/routines/run/{run_id}/results", headers=HEADERS)
        resp.raise_for_status()
        body = resp.json()
        if body["status"] == "complete":
            return body.get("data", [])
        time.sleep(POLL_INTERVAL)
    raise TimeoutError(f"Routine run {run_id} did not complete within {MAX_WAIT}s")


@app.route("/find-email", methods=["POST"])
def find_email():
    prospects = (request.get_json(silent=True) or {}).get("prospects", [])
    run_id = submit(prospects)
    items = poll(run_id)
    emails = [{"id": item["id"], "work_email": (item.get("result") or {}).get("Work Email")} for item in items]
    return jsonify({"emails": emails, "routine_run_id": run_id})


if __name__ == "__main__":
    app.run(port=5010)

python app.py

curl -s -X POST http://localhost:5010/find-email \
  -H "Content-Type: application/json" \
  -d '{"prospects": [{"full_name": "Jane Doe", "company_name": "Acme Corp", "company_domain": "acme.com"}]}'

{
  "emails": [{"id": "prospect-0", "work_email": "[email protected]"}],
  "routine_run_id": "run_0tjzckba2vesmp7ZTo5"
}

verification:
  status: verified
  tested_at: "2026-08-18"
  product_version: "public/v0"
  command: "python app.py && curl -s -X POST http://localhost:5010/find-email -d '{\"prospects\":[{\"full_name\":\"Kareem Amin\",\"company_name\":\"Clay\",\"company_domain\":\"clay.com\"}]}'"
  expected_result: "HTTP 200, real deliverable work_email returned for the tested prospect (~16s completion time)"