Перенесення перевірки e-mail з Hunter або Apollo в Cold Leads

Що переноситься, а що лишається

• Переноситься: перевірка окремих адрес (Hunter Email Verifier) — на POST /api/v1/verify, списки — на POST /api/v1/verify/bulk (до 5 000 адрес у завданні), а пошук імовірної адреси за іменем і доменом (Hunter Email Finder) — на POST /api/v1/find.
• Лишається: Domain Search від Hunter і вебджерела, на яких ґрунтуються його результати, а також People Search, People Enrichment і Bulk People Enrichment від Apollo. Cold Leads не має бази людей чи компаній; GET /api/v1/leads шукає лише серед контактів у вашій власній CRM Cold Leads.
• Публічний API Apollo не має окремого ендпоінта перевірки; email_status приходить разом із даними про людину. Якщо ви лишаєте Apollo як джерело даних, адреси, які він повертає, можна перевірити в Cold Leads перед надсиланням.

Заміна Email Verifier на POST /api/v1/verify

Заміна Email Finder на POST /api/v1/find

Адаптер для прямої заміни

Якщо ваш код розгалужується за назвами полів Hunter, ці дві функції повертають ту саму структуру з даних Cold Leads, а також сиру відповідь у полі coldleads. Зіставлення навмисно консервативне: адреса, скриньку якої не перевірено (smtp_unreachable), стає unknown, а не 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"))

Відмінності в поведінці, які варто врахувати

• Коди помилок: Cold Leads відповідає 429 у разі перевищення ліміту запитів (rate_limited, з Retry-After: 60) і коли відкрито забагато масових завдань (too_many_jobs), а 402 no_credits — коли закінчилися кредити. Hunter документує 403 для свого ліміту запитів і 429 для ліміту використання, тож обробку помилок доведеться переписати, а не просто перейменувати.
• Ліміт запитів: 120 запитів на хвилину на ключ. Для списків одне масове завдання замінює до 5 000 окремих викликів.
• Кожен виклик коштує 1 кредит, зокрема й для результатів із 30-денного кешу.
• SMTP-перевірка скриньки та accept-all виконується лише тоді, коли Cold Leads може відкрити SMTP-з’єднання з поштовим сервером одержувача. reasons кожного результату показують, чи вона відбулася: smtp_unreachable означає, що скриньку не перевірено.

Ліміти та вартість

API є лише в тарифі Business, який можна оплачувати й щороку ($999). Виклики пошуку адреси списують ті самі кредити, 1 за виклик. Місячні кредити рахуються за календарний місяць (UTC) і використовуються раніше за куплені пакети. Ціни вказано в доларах США; може додаватися податок.

Питання