E-Mail-Verifizierung von Hunter oder Apollo zu Cold Leads migrieren

Was umzieht und was bleibt

• Zieht um: Einzelprüfungen (Hunter Email Verifier) zu POST /api/v1/verify, Listen zu POST /api/v1/verify/bulk (bis zu 5.000 Adressen pro Auftrag) und Vermutungen aus Name und Domain (Hunter Email Finder) zu POST /api/v1/find.
• Bleibt: Hunters Domain Search samt den Webquellen hinter ihren Ergebnissen sowie Apollos People Search, People Enrichment und Bulk People Enrichment. Cold Leads hat keine Datenbank mit Personen oder Unternehmen; GET /api/v1/leads durchsucht nur die Kontakte in Ihrem eigenen Cold-Leads-CRM.
• Apollos öffentliche API hat keinen eigenständigen Prüf-Endpunkt; email_status kommt mit den Personendaten. Wenn Sie Apollo für Daten behalten, können Sie die gelieferten Adressen vor dem Versand mit Cold Leads prüfen.

Email Verifier zu POST /api/v1/verify

Email Finder zu POST /api/v1/find

Ein Drop-in-Adapter

Wenn Ihr Code nach Hunters Feldnamen verzweigt, liefern diese beiden Funktionen dieselbe Struktur aus Cold Leads, dazu die Rohantwort unter coldleads. Die Zuordnung ist bewusst vorsichtig: Eine Adresse, deren Postfach nicht geprüft wurde (smtp_unreachable), wird zu unknown, nicht zu valid.

# pip install httpx
# Drop-in helpers for code written against Hunter's email-verifier and email-finder.
# They call Cold Leads and return Hunter-style fields, plus the raw Cold Leads answer.
import os

import httpx

cold = httpx.Client(
    base_url="https://coldleads.app/api/v1",
    headers={"x-api-key": os.environ["COLDLEADS_API_KEY"]},  # the key goes in a header, never in the URL
    timeout=40.0,
)

# a mail server answered the SMTP probe only when the last reason is one of these
PROBED = {"ok", "catch_all", "mailbox_missing"}


def email_verifier(email: str) -> dict:
    r = cold.post("/verify", json={"email": email, "timeout_ms": 20000})
    r.raise_for_status()
    c = r.json()
    last = c["reasons"][-1]
    if c["disposable"] and last not in ("syntax", "no_mx"):
        status = "disposable"
    elif last == "ok":
        status = "valid"
    elif last == "catch_all":
        status = "accept_all"
    elif last in ("mailbox_missing", "no_mx", "syntax"):
        status = "invalid"
    else:
        # smtp_unreachable (mailbox not checked), smtp_unknown or timeout: not verified
        status = "unknown"
    return {
        "email": c["email"],
        "status": status,
        "score": c["score"],
        "regexp": last != "syntax",
        "disposable": c["disposable"],
        "mx_records": c["mx"] is not None,
        "smtp_check": last in ("ok", "catch_all"),
        "accept_all": c["catch_all"] if last in PROBED else None,  # None: not tested
        "coldleads": c,
    }


def email_finder(domain: str, first_name: str = "", last_name: str = "", full_name: str = "") -> dict:
    body = {"domain": domain, "first": first_name, "last": last_name}
    if full_name and not (first_name or last_name):
        body = {"domain": domain, "name": full_name}
    r = cold.post("/find", json=body)
    r.raise_for_status()
    c = r.json()
    return {
        "email": c["email"],
        "score": c["confidence"],
        "accept_all": c["catch_all"],
        # Cold Leads says "verified" only when a mail server confirmed the mailbox; a pattern guess is not verified
        "verification": {"status": "valid" if c["method"] == "verified" else None},
        "coldleads": c,
    }


if __name__ == "__main__":
    print(email_verifier("anna@example.com"))

Verhaltensunterschiede, die Sie einplanen sollten

• Fehlercodes: Cold Leads antwortet mit 429 bei seinem Ratenlimit (rate_limited, mit Retry-After: 60) und bei zu vielen offenen Bulk-Aufträgen (too_many_jobs) sowie mit 402 no_credits, wenn die Credits ausgehen. Hunter dokumentiert 403 für sein Ratenlimit und 429 für sein Nutzungslimit; die Fehlerbehandlung muss also neu geschrieben und nicht nur umbenannt werden.
• Ratenlimit: 120 Anfragen pro Minute und Schlüssel. Bei Listen ersetzt ein Bulk-Auftrag bis zu 5.000 Einzelaufrufe.
• Jeder Aufruf kostet 1 Credit, auch für Ergebnisse aus dem 30-Tage-Cache.
• Die SMTP-Prüfung von Postfach und Accept-all läuft nur, wenn Cold Leads eine SMTP-Verbindung zum Mailserver des Empfängers aufbauen kann. Die reasons jedes Ergebnisses zeigen, ob sie gelaufen ist: smtp_unreachable bedeutet, dass das Postfach nicht geprüft wurde.

Limits und Kosten

Die API gibt es nur im Business-Tarif, der auch jährlich bezahlt werden kann ($999). Aufrufe der Adresssuche verbrauchen dieselben Credits, 1 pro Aufruf. Monatliche Credits zählen pro Kalendermonat (UTC) und werden vor gekauften Paketen verbraucht. Preise in US-Dollar; es können Steuern anfallen.

FAQ