Praxisrezepte für Entwickler und Automatisierer. Jeder Beitrag enthält eine konkrete Konfiguration, einen Workflow oder ein Skript für die Cold-Leads-API und nennt die geltenden Limits und Credit-Kosten. Die API braucht einen geheimen Schlüssel aus dem Tarif Business.
Adressen, IDs und Ergebnisse in den Beispielen sind illustrativ. example.com ist für Dokumentation reserviert, eine echte Prüfung dieser Adressen liefert daher invalid.
Entwickler, die KI-Assistenten in Cursor, Claude Desktop oder Windsurf nutzen6 Min. Lesezeit
Adressen zwischen Assistent, CRM und Prüf-Tool hin- und herzukopieren ist langsam und fehleranfällig, und ein Assistent, den man nach Kontakten fragt, erfindet bereitwillig welche.
Ein verbundener Assistent kann Ihre Kontakte verwalten, strukturierte Zeilen importieren, synchronisierte Gespräche lesen, Vorlagen und Kampagnenentwürfe pflegen und Website-Formulare einrichten. Der Versand erfordert Ihre ausdrückliche Bestätigung und unterliegt den Einwilligungs-, Abmelde-, DNC- und Kontoschutzregeln von Cold Leads.
Was Sie bekommen: Ein Assistent, der über MCP oder das Node SDK mit Ihren Kontakten, Ihrem Postfach und Kampagnenentwürfen arbeitet.
Eine Prüf-API einmal pro Zeile aufzurufen ist langsam und stößt an Ratenlimits, eine Bulk-API dagegen braucht einen Auftrag, eine Polling-Schleife und einen zuverlässigen Weg, die Ergebnisse den richtigen Zeilen zuzuordnen.
Ein Workflow nimmt bis zu 5.000 Zeilen, die noch kein Ergebnis haben, sendet ihre eindeutigen Adressen als einen einzigen Cold-Leads-Bulk-Auftrag, fragt den Auftrag alle 5 Sekunden ab, holt die Ergebnisse, verteilt jede Zeile nach Status und schreibt Status, Score, Grund und einen nächsten Schritt in das Sheet. Für die nächsten 5.000 führen Sie ihn erneut aus.
Was Sie bekommen: Vier ausgefüllte Spalten pro Zeile (verify_status, verify_score, verify_reason, next_step) und ein Workflow, den Sie erneut ausführen können, bis das ganze Sheet fertig ist.
Nie geprüfte Adressen landen direkt in einer Versandkampagne. Die ungültigen bouncen, und Bounces gehen zulasten der Postfächer, die die Kampagne versenden.
Setzen Sie eine Cold-Leads-Prüfung zwischen Trigger und Instantly: eine HTTP-Anfrage pro Lead, einen Filter, der nur gültige Ergebnisse durchlässt, und eine zweite HTTP-Anfrage, die den Lead mit der Instantly API v2 Ihrer Kampagne hinzufügt.
Was Sie bekommen: Ein laufendes Make-Szenario: neuer Lead, Cold-Leads-Prüfung, Filter, Lead in der Instantly-Kampagne. Leads, die den Filter nicht passieren, bleiben dort stehen oder landen in einem Sheet zur manuellen Prüfung.
Cold-Leads-Modul, Body content
{
"email": "{{map the e-mail field of the trigger here}}",
"timeout_ms": 10000
}
Eine Adresse pro Anfrage zu prüfen ist langsam und stößt an das Ratenlimit. Eine naive Bulk-Schleife kann mehr Aufträge öffnen, als das Konto erlaubt, nach einem Absturz doppelt bezahlen oder stillschweigend Zeilen verlieren, deren Ergebnisse nie zurückkamen.
Normalisieren und deduplizieren Sie die Spalte, senden Sie Bulk-Aufträge mit bis zu 5.000 Adressen, halten Sie höchstens fünf offen, fragen Sie jeden Auftrag bis zum Ende ab, warten Sie Ratenlimits ab, stoppen Sie sauber, wenn die Credits ausgehen, und speichern Sie die Auftrags-IDs, damit ein zweiter Lauf fortsetzt, statt erneut zu bezahlen.
Was Sie bekommen: Ihre CSV mit drei neuen Spalten (verify_status, verify_score, verify_reason) und eine kleine .jobs.json-Datei, die den Lauf fortsetzbar macht.
verify_csv.py
"""Verify a large CSV with the Cold Leads bulk API (Python 3.9+, httpx).
pip install httpx
export COLDLEADS_API_KEY=sk_...
python verify_csv.py leads.csv leads_verified.csv --column email
Addresses are normalised and de-duplicated, sent in jobs of up to 5,000 with at most
5 jobs open at a time, and every job is polled until it is done. The output is the
input CSV plus verify_status, verify_score and verify_reason. Job ids are saved next
to the output file, so a second run resumes the same jobs instead of paying twice.
Prüfcode steckt voller anbieterspezifischer Parameter und Statuswerte. Wer nur den Endpunkt austauscht, ohne sie abzubilden, ändert stillschweigend, an welche Adressen eine Pipeline sendet.
Bilden Sie jeden Parameter und jedes Antwortfeld auf sein Gegenstück bei Cold Leads ab, lassen Sie, was Cold Leads nicht ersetzt (Personendaten, Domainsuche), wo es ist, und nutzen Sie einen kleinen Adapter, damit bestehender Code seine Form behält.
Was Sie bekommen: Eine Zuordnung Feld für Feld, ein Python-Adapter, der Felder im Hunter-Stil aus Cold Leads liefert, und eine Tabelle der Cold-Leads-Kosten für 1.000, 10.000 und 50.000 Prüfungen im Monat.
hunter_adapter.py
# 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
Ein Agent, der E-Mail-Prüfung braucht, sollte nie eine Karte besitzen oder selbst ein Abonnement abschließen. Den Menschen loszuschicken, damit er sich registriert, einen Tarif wählt und einen Schlüssel kopiert, unterbricht die Aufgabe, und in Chats eingefügte Schlüssel werden offengelegt.
Der Agent ruft ohne Schlüssel einen Endpunkt auf und erhält einen Stripe-Checkout-Link für seinen Inhaber sowie ein geheimes Claim-Token. Der Inhaber prüft den Tarif und entscheidet. Nach der Zahlung holt der Agent den API-Schlüssel mit dem Claim-Token genau einmal ab, per Polling oder nach einem signierten Callback.
Was Sie bekommen: Ein funktionierender geheimer API-Schlüssel für das neue Business-Konto des Inhabers, einmal an den Agenten ausgeliefert, und eine E-Mail an den Inhaber mit einem Link, der die Cold-Leads-Web-App öffnet.
Manche Mailserver nehmen E-Mails für jede Adresse ihrer Domain an, sodass eine Postfachprüfung eine echte Person nicht von einem erfundenen Namen unterscheiden kann. Andere Server antworten nur vorläufig oder sind gar nicht erreichbar, und eine bloße Einstufung als valid kann verbergen, dass das Postfach nie geprüft wurde.
Verstehen Sie den SMTP-Dialog, den ein Prüfdienst führt, und was jede Antwort bedeutet, und lesen Sie dann Status, Score und Grundcodes, die Cold Leads liefert, einschließlich der Fälle, in denen die Postfachprüfung nicht gelaufen ist.
Was Sie bekommen: Eine Entscheidungstabelle, die jedem Grundcode von Cold Leads eine Aktion zuordnet, und ein Skript, das sie auf eine Adresse anwendet.
Zwei SMTP-Sitzungen (Illustration)
# Session 1: is the address accepted?
S: 220 mx1.example.com ESMTP
C: EHLO verifier.example.net
S: 250-mx1.example.com
S: 250 SIZE 52428800
C: MAIL FROM:<check@verifier.example.net>
S: 250 2.1.0 Sender OK
C: RCPT TO:<anna@example.com>
S: 250 2.1.5 Recipient OK <- accepted (a 550 here would mean: rejected)
C: QUIT <- no DATA command: nothing is delivered
In diesem Rezept
Der SMTP-Dialog hinter einer Postfachprüfung
Antwortcodes und welche Schlüsse sie erlauben
Accept-all-Test, Greylisting und andere Grenzen
Was Cold Leads zurückgibt und wann der Test nicht lief
Eine Entscheidungstabelle und ein Skript, das sie anwendet
Kontakte kommen aus Formularen, Importen und manueller Eingabe mit Tippfehlern, toten Domains oder ganz ohne Adresse, und niemand prüft sie, bis eine Kampagne Bounces erzeugt.
Prüfen Sie jeden Kontakt beim Anlegen: mit einer Custom-Code-Aktion in einem HubSpot-Workflow oder einem kleinen Webhook-Empfänger für Pipedrive. Ein Kontakt mit E-Mail-Adresse wird geprüft; ein Kontakt ohne, aber mit Namen und Firmenwebsite erhält eine vorgeschlagene Adresse, die klar als Vermutung gekennzeichnet ist.
Was Sie bekommen: Kontakteigenschaften in HubSpot oder Personenfelder in Pipedrive, die Status, Score und Grund von Cold Leads zeigen oder eine vorgeschlagene Adresse mit Methode und Konfidenz.
Custom code (Node.js)
// HubSpot workflow, Custom code action (Node.js)
// Secret: COLDLEADS_API_KEY (your Cold Leads secret key, sk_...)
// Properties to include in code: email, firstname, lastname, website
// Data outputs (add them in the action): verify_status, verify_reason, suggested_email, find_method (String);
// verify_score, find_confidence (Number); mailbox_checked (Boolean)
const axios = require("axios");
const coldleads = axios.create({
baseURL: "https://coldleads.app/api/v1",
headers: { "x-api-key": process.env.COLDLEADS_API_KEY },
In diesem Rezept
Wie alles zusammenpasst
HubSpot: eine Custom-Code-Aktion in einem Kontakt-Workflow
Pipedrive: ein Webhook-Empfänger
Was zurückgeschrieben wird und was damit zu tun ist
Ein Agent, den man nach Kontaktdaten fragt, rät, und eine geratene Adresse sieht genauso aus wie eine echte. Ohne ein Prüf-Tool können weder der Agent noch die Person, die seine Ausgabe liest, den Unterschied erkennen.
Geben Sie dem Agenten drei eng gefasste Tools auf Basis der Cold-Leads-API: das eigene CRM des Nutzers durchsuchen, eine Adresse prüfen und eine Adresse aus Name und Domain erraten, mit einer ehrlichen Angabe der method. Fehler kommen als Daten zurück, sodass der Agent reagieren kann, statt abzustürzen.
Was Sie bekommen: Ein gemeinsamer API-Client, Tool-Klassen für CrewAI und für LangChain sowie eine minimale Crew und ein minimaler Agent, die sie nutzen.
coldleads_tools.py
# coldleads_tools.py - shared by the CrewAI and LangChain examples (pip install httpx)
import json
import os
import httpx
VERIFY_DESC = (
"Verify one e-mail address with Cold Leads (costs 1 credit). Returns status valid, risky or invalid, "
"a score from 0 to 100 and reason codes. The last reason says what was checked: ok means a mail server "
"accepted the mailbox, smtp_unreachable means the mailbox itself was not checked, catch_all means the "
In diesem Rezept
Die drei Tools
Ein gemeinsamer Client
CrewAI
LangChain
Beschreibungen, mit denen das Modell arbeiten kann
Ein Sheet in ein Prüf-Tool zu exportieren und die Ergebnisse zurückzukopieren ist mühsam. Eine naive benutzerdefinierte Funktion ruft die API jedes Mal erneut auf und verbraucht erneut einen Credit, wenn Sheets die Formel erneut ausführt.
Zwei benutzerdefinierte Funktionen rufen die Cold-Leads-API mit UrlFetchApp auf, lesen den Schlüssel aus den Skripteigenschaften (Script Properties) und halten jede Antwort bis zu sechs Stunden im Skript-Cache; eine erneute Ausführung derselben Formel verbraucht für dieselbe Eingabe also keinen weiteren Credit.
Was Sie bekommen: Drei Ergebniszellen pro Zeile: Status, Score und Grund aus =VERIFY_EMAIL oder Adresse, Methode und Konfidenz aus =FIND_EMAIL.
Code.gs
// Cold Leads custom functions for Google Sheets (Extensions → Apps Script, paste into Code.gs).
// Key: Project Settings → Script Properties → Add script property COLDLEADS_API_KEY = sk_...
const COLDLEADS_API = 'https://coldleads.app/api/v1';
const CACHE_SECONDS = 21600; // 6 hours, the longest CacheService keeps an entry
/**
* Verifies an e-mail address with Cold Leads. Fills three cells: status, score, last reason code.
* Costs 1 Cold Leads credit unless the same address was answered from this script's cache.
*
* @param {string} email The address, for example A2.
