Cómo migrar la verificación de correos de Hunter o Apollo a Cold Leads

Qué se traslada y qué se queda

• Se traslada: las comprobaciones de una sola dirección (Hunter Email Verifier) a POST /api/v1/verify, las listas a POST /api/v1/verify/bulk (hasta 5 000 direcciones por tarea) y las deducciones a partir de nombre y dominio (Hunter Email Finder) a POST /api/v1/find.
• Se queda: Domain Search de Hunter y las fuentes web detrás de sus resultados, y People Search, People Enrichment y Bulk People Enrichment de Apollo. Cold Leads no tiene una base de datos de personas ni de empresas; GET /api/v1/leads solo busca en los contactos de su propio CRM de Cold Leads.
• La API pública de Apollo no tiene un endpoint de verificación independiente; email_status llega con los datos de la persona. Si mantiene Apollo para los datos, puede comprobar con Cold Leads las direcciones que devuelve antes de enviar.

De Email Verifier a POST /api/v1/verify

De Email Finder a POST /api/v1/find

Un adaptador de sustitución directa

Si su código se ramifica según los nombres de campo de Hunter, estas dos funciones devuelven la misma forma a partir de Cold Leads, más la respuesta original bajo coldleads. El mapeo es deliberadamente conservador: una dirección cuyo buzón no se comprobó (smtp_unreachable) pasa a ser unknown, no 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"))

Diferencias de comportamiento que debe prever

• Códigos de error: Cold Leads responde 429 por su límite de peticiones (rate_limited, con Retry-After: 60) y por demasiadas tareas masivas abiertas (too_many_jobs), y 402 no_credits cuando se acaban los créditos. Hunter documenta 403 para su límite de peticiones y 429 para su límite de uso, así que hay que reescribir el manejo de errores, no basta con renombrar.
• Límite de peticiones: 120 peticiones por minuto por clave. Para listas, una tarea masiva sustituye hasta 5 000 llamadas individuales.
• Cada llamada cuesta 1 crédito, incluidos los resultados servidos desde la caché de 30 días.
• La comprobación SMTP del buzón y de accept-all solo se ejecuta cuando Cold Leads puede abrir una conexión SMTP con el servidor de correo del destinatario. Los reasons de cada resultado indican si se ejecutó: smtp_unreachable significa que el buzón no se comprobó.

Límites y costes

La API solo está en el plan Business, que también se puede pagar anualmente ($999). Las llamadas de búsqueda (find) consumen los mismos créditos, 1 por llamada. Los créditos mensuales se cuentan por mes natural (UTC) y se usan antes que los paquetes comprados. Los precios están en dólares estadounidenses; pueden aplicarse impuestos.

Preguntas frecuentes