Usare chiavi API in un Waterfall Email Finder

Un waterfall email finder personalizzato ti permette di utilizzare diversi provider di email finder nell’ordine che preferisci, usando le tue chiavi API. Scelgo questa configurazione quando il normale waterfall gestito non è il vero limite. La priorità, in questi casi, è avere controllo: decidere quale provider interrogare per primo, come spendere i crediti dei provider esterni e quanto del workflow mantenere in un unico workspace dedicato alle liste di lead.

In Datablist, il workflow è semplice. Importa una lista di lead, apri Waterfall Email Finder, lascia il metodo di ricerca su By Name and Company, attiva Custom Waterfall, aggiungi i provider e le rispettive chiavi API, mappa le colonne di input, crea le colonne di output, esegui un’anteprima e infine elabora la lista. Durante le esecuzioni personalizzate, Datablist gestisce anche le risposte temporanee dovute ai rate limit dei provider, evitando che un rallentamento momentaneo causi subito l’errore della riga.

La distinzione importante sul prezzo è questa: Datablist non addebita crediti Datablist per le esecuzioni valide con chiavi API personalizzate. Continuerai comunque a pagare i provider esterni tramite i tuoi account, secondo i rispettivi piani e le regole delle loro API. Ecco perché l’ordine dei provider conta.

Link rapidi

• Come funziona un waterfall email finder personalizzato
• Esempio di CSV con lead
• Preparare le chiavi API dei provider
• Configurare Custom Waterfall in Datablist
• Mappare input e colonne di output
• Eseguire un’anteprima e verificare i risultati
• Esportare o continuare ad arricchire la lista

Come funziona un waterfall email finder personalizzato

Un waterfall interroga più provider di dati in sequenza. Per ogni lead viene consultato il primo provider. Se restituisce un indirizzo email utilizzabile, l’elaborazione della riga si ferma. Se non trova alcun indirizzo, entra in gioco il provider successivo. La sequenza continua finché non viene trovata un’email o non sono stati interrogati tutti i provider.

È il principio alla base del waterfall enrichment: non affidarsi a un’unica fonte di dati quando un’altra potrebbe avere una copertura migliore per lo stesso contatto.

Un waterfall personalizzato aggiunge un ulteriore livello di controllo. Invece di usare una sequenza di provider gestita, scegli tu i provider e autentichi ciascuno con la tua chiave API. Datablist gestisce l’esecuzione riga per riga, la mappatura degli input, le colonne di output e lo stato dell’elaborazione. Tu decidi l’ordine.

In Datablist, la sequenza personalizzata è disponibile nel Waterfall Email Finder quando il metodo di ricerca è By Name and Company. I provider supportati nella sequenza personalizzata sono Icypeas, Enrow, Prospeo, Wiza, Findymail, LeadMagic, TryKitt, Enrich.so e FullEnrich.

Il waterfall predefinito di Datablist è più semplice. Datablist gestisce la sequenza dei provider e addebita 25 crediti Datablist per ogni email di lavoro trovata. Spesso è l’opzione migliore se non vuoi gestire gli account dei vari provider.

Custom Waterfall è più indicato se hai già abbonamenti ai provider, crediti esterni inutilizzati o un valido motivo per testare un ordine personalizzato. Se stai ancora valutando quale workflow scegliere tra quello gestito e quello personalizzato, consulta questa guida più ampia su come trovare email su larga scala.

🔑 Decisione chiave

Usa Custom Waterfall quando l’ordine dei provider e il controllo dei costi esterni sono più importanti di una sequenza completamente gestita.

Esempio di CSV con lead

Per questa guida userò un export di lead di esempio. I nomi delle persone e le email restituite sono puramente illustrativi: servono a mostrare il workflow, non ad affermare che queste persone lavorino nelle aziende indicate.

Il file contiene queste colonne:

Per Email Finder, gli input obbligatori sono First Name e Last Name, oppure un unico campo Full Name, più un campo relativo all’azienda. Quest’ultimo può contenere un dominio o il nome dell’azienda. Quando disponibili, preferisco i domini perché eliminano le ambiguità legate ai nomi aziendali.

Quando il valore mappato è un nome aziendale, Datablist prova a individuare internamente un dominio verificato prima di interrogare i provider personalizzati. Questa ricerca fa parte di Email Finder e non richiede un’esecuzione separata per convertire il nome dell’azienda in dominio. LinkedIn Profile URL può essere utile se disponi di URL standard dei profili LinkedIn, ma questa guida alla sequenza personalizzata si basa sul metodo By Name and Company.

Le altre colonne non vengono mappate in Email Finder, ma le conservo comunque. Job Title, Lead Source e Market sono utili per controllare la lista dopo l’enrichment e segmentare l’export in un secondo momento.

💡 Consiglio pratico

Conserva le colonne di origine. È molto più facile capire perché una riga non è stata elaborata quando nome dell’azienda, dominio, fonte e mercato sono ancora visibili accanto al risultato dell’enrichment.

Preparare le chiavi API dei provider

Prima di aprire l’enrichment, assicurati di avere a disposizione tre elementi:

• Una collection Datablist con i dati dei lead.
• Account attivi per i provider di email finder che vuoi utilizzare.
• Le chiavi API copiate dagli account dei provider.

Il mio ordine abituale non parte necessariamente dal “provider più economico”. Inizio dal provider che offre il miglior equilibrio tra costo, copertura e qualità dei risultati per il mercato che sto testando. Un provider economico ma con una copertura scarsa può essere una pessima prima scelta se restituisce troppi risultati poco affidabili o trova raramente le email degli account target.

Una buona sequenza iniziale può essere questa:

La configurazione comprende la sequenza dei provider, la mappatura degli input e quella degli output.

⚠️ Attenzione ai costi

Datablist non addebita crediti per le esecuzioni valide con chiavi API personalizzate, ma ogni provider esterno può comunque applicare costi tramite il proprio account, il listino API o il sistema di crediti.

Configurare Custom Waterfall in Datablist

Passaggio 1: importa la lista di lead

Crea una nuova collection Datablist oppure aprine una esistente, quindi importa il file CSV o Excel. Dopo l’importazione, controlla che le colonne siano state interpretate correttamente prima di avviare qualsiasi enrichment.

Di solito verifico tre aspetti:

• I nomi sono separati tra First Name e Last Name, oppure il file contiene un’unica colonna pulita con il nome completo.
• Le informazioni sull’azienda sono disponibili sotto forma di dominio, sito web o nome aziendale.
• I campi aggiuntivi, come ruolo, fonte e mercato, sono rimasti nella collection.

Questo passaggio può sembrare banale, ma determina la qualità dell’intero workflow. Se la fonte dei lead contiene nomi aziendali incoerenti, domini mancanti o URL LinkedIn incollati nella colonna sbagliata, correggi prima i problemi più evidenti.

Datablist conserva il file in una collection simile a un foglio di calcolo, così puoi filtrare, arricchire, pulire ed esportare i dati senza spostarli da uno strumento all’altro.

Passaggio 2: apri Waterfall Email Finder

Apri il pannello degli enrichment e seleziona Waterfall Email Finder.

Per questo workflow, lascia Email Search Method impostato su By Name and Company (default). È il metodo con cui viene configurato Custom Waterfall e richiede il nome di una persona insieme alle informazioni sull’azienda.

Datablist offre anche il metodo By LinkedIn URL per le liste basate su URL standard dei profili LinkedIn. È utile in altri workflow, ma non lo userei per questa sequenza personalizzata a meno che gli input non siano adatti a quel metodo. Gli URL dei profili Sales Navigator non sono supportati da questo enrichment, quindi non considerarli un sostituto diretto degli URL standard dei profili LinkedIn.

Se stai ancora confrontando i diversi approcci di ricerca, questa guida sui metodi per trovare l’indirizzo email di una persona spiega quando conviene usare un waterfall rispetto a una ricerca con un singolo provider o a metodi manuali.

Passaggio 3: attiva Custom Waterfall e aggiungi i provider

Nelle impostazioni dell’enrichment, lascia il metodo di ricerca su By Name and Company (default).

Scegli quindi il formato del nome:

• Se il file contiene First Name e Last Name, lascia Use Full Name disattivato.
• Se il file contiene un’unica colonna per il nome, attiva Use Full Name e mappa la colonna in seguito.

A questo punto, attiva Custom Waterfall. Datablist mostrerà la sezione Waterfall Sequence. Aggiungi una riga per ogni provider. In ciascuna riga, seleziona il provider e incolla la chiave API del relativo account.

La sequenza viene eseguita per ogni singola riga. Se il provider 1 trova un’email, l’elaborazione si ferma. Se non trova nulla, Datablist prova il provider 2. Se nessun provider restituisce un indirizzo, la riga riceve il risultato not_found.

Nella modalità personalizzata, gli eventuali problemi di configurazione dei provider vengono segnalati, così puoi correggerli. È utile perché chiavi API non valide, problemi di quota o di accesso all’account devono essere risolti, non nascosti dietro un fallback gestito.

Per iniziare, userei una sequenza di questo tipo:

Uso volutamente etichette generiche. L’ordine migliore dipende dagli account che possiedi, dal mercato target e dai tuoi requisiti sulla qualità delle email.

📘 Esempio di sequenza

Parti con una sequenza breve, esegui un’anteprima e aggiungi altri provider solo se la copertura aggiuntiva giustifica il costo esterno.

Mappare input e colonne di output

Passaggio 4: mappa le colonne di input

Ora associa le colonne di origine agli input dell’enrichment.

Per l’export di esempio, imposterei questa mappatura:

Se hai attivato Use Full Name, associa l’unica colonna con il nome a Full Name, invece di mappare separatamente nome e cognome.

La mappatura dell’input si applica a una sola colonna di origine. Se il file conserva domini e nomi aziendali in colonne separate, mappa quella con la copertura migliore oppure prepara un’unica colonna che contenga il dominio, quando disponibile, e in alternativa il nome dell’azienda. Quando mappi i nomi aziendali, Datablist tenta di risolvere internamente il dominio prima di avviare la sequenza dei provider. I nomi ambigui possono comunque essere confusi con quelli di filiali, vecchie denominazioni o aziende omonime.

Non eliminare le righe con dati mancanti prima dell’esecuzione. Preferisco conservarle, avviare l’enrichment e usare gli stati dei risultati per isolare i problemi. Le righe prive del nome o dei dati aziendali possono restituire missing_source_data. Quelle con input malformati possono restituire invalid_data.

Questo stato è utile: crea una coda di dati da correggere senza costringerti a indovinare quali righe non hanno funzionato.

Passaggio 5: crea le colonne di output

Aggiungi le colonne di output alla collection. In alternativa, associale a colonne esistenti se ne hai già di simili.

Questi sono gli output disponibili:

Dopo un’esecuzione personalizzata, controllo per prima la colonna Finder Provider. Indica quale provider ha effettivamente prodotto il risultato. Senza questa informazione puoi vedere l’email, ma non valutare l’efficacia della sequenza.

MX Provider indica invece il provider della casella di posta associato all’email, per esempio Google, Microsoft, Mimecast, Proofpoint o un altro servizio.

Eseguire un’anteprima e verificare i risultati

Passaggio 6: esegui un’anteprima prima dell’intera lista

Esegui l’enrichment su un piccolo gruppo di righe prima di elaborare l’intera collection. Lo faccio anche quando sono sicuro delle chiavi API: un’anteprima permette di individuare mappature errate e problemi di configurazione prima che interessino tutta la lista.

Controlla cinque aspetti nell’anteprima:

• Le chiavi API vengono accettate.
• I valori di Finder Provider compaiono quando vengono trovate delle email.
• I valori di Email Status sono plausibili.
• I campi mancanti restituiscono missing_source_data anziché celle vuote difficili da interpretare.
• Il primo provider non produce troppi risultati unverified di bassa qualità.

È qui che l’ordine dei provider diventa concreto. Se il provider 1 restituisce molte email non verificate e il provider 2 ne trova meno ma con più risultati verificati, potrebbe essere opportuno invertirli o ampliare il test.

🔍 Scorciatoia per la verifica

Filtra le righe dell’anteprima per Email Status e Finder Provider. È il modo più rapido per capire se il primo provider merita davvero quella posizione nella sequenza.

Passaggio 7: esegui Custom Waterfall su tutte le righe

Quando l’anteprima è soddisfacente, seleziona le righe da elaborare ed esegui l’enrichment sull’intera lista.

Per ogni riga, Datablist segue la sequenza configurata. Una riga elaborata correttamente riceve un’email e uno stato. Se nessun provider trova un risultato, riceve not_found. Se mancano il nome o i dati dell’azienda, viene assegnato uno stato relativo ai dati mancanti. Gli input malformati possono invece essere contrassegnati come non validi.

Datablist gestisce anche i rate limit temporanei dei provider durante le esecuzioni personalizzate. Se un provider rallenta momentaneamente o restituisce una risposta di rate limit, Datablist può riprovare invece di contrassegnare subito la riga come errore del provider. È un aspetto importante quando elabori liste estese con le tue chiavi API, perché spesso i provider esterni limitano la frequenza delle richieste prima di rifiutarle del tutto.

Questo non elimina i limiti imposti dai provider. Servono comunque chiavi API valide, account attivi e crediti o quota esterna sufficienti. Il vantaggio è che Datablist gestisce orchestrazione, nuovi tentativi in caso di rate limit, output e stato della verifica all’interno della stessa collection.

Verificare i risultati e correggere le righe non riuscite

Al termine dell’esecuzione, la collection dovrebbe contenere i campi originali dei lead e gli output di Email Finder.

Ecco una tabella esemplificativa dei risultati:

I nomi e gli indirizzi email della tabella sono illustrativi. Usa questo schema per comprendere l’output, non come fonte di dati di contatto reali.

Di solito suddivido la verifica in quattro gruppi:

• verified: conserva questi contatti per l’outreach, applicando i normali controlli previsti per le campagne.
• unverified: controllali prima dell’invio, soprattutto se il rischio di bounce è importante.
• missing_source_data o invalid_data: correggi i campi di origine, quindi esegui di nuovo quelle righe.
• not_found: valuta se provare un’altra sequenza di provider, fare una ricerca manuale o lasciare vuoto il campo email.

La colonna Finder Provider è utile anche per analizzare i costi. Confrontala con i tuoi account presso i provider. Se la maggior parte delle email viene trovata dal provider 3, il provider 1 potrebbe non generare abbastanza valore. Se invece il provider 1 trova email valide per quasi tutte le righe, i provider di fallback stanno probabilmente svolgendo bene il loro compito: intercettare i contatti più difficili.

Non valutare la sequenza solo in base al numero di email trovate. Considera anche la qualità dello stato, il rischio di bounce e il costo esterno. Un provider che restituisce molte email non verificate può sembrare produttivo in un foglio di calcolo, ma creare problemi di deliverability in seguito.

Esportare o continuare ad arricchire la lista

Quando i risultati sono puliti, esporta la lista arricchita in formato CSV o Excel.

Prima dell’export puoi anche continuare a lavorare in Datablist:

• Filtrare i lead verificati.
• Deduplicare i contatti.
• Arricchire le aziende con altri dati firmografici.
• Segmentare per Market, Lead Source o Job Title.
• Preparare un file da importare nel CRM.

È per questo che preferisco mantenere il workflow all’interno di una collection. La ricerca delle email è spesso solo una fase di un processo più ampio di preparazione dei lead. Prima di inviare la lista a un CRM o a uno strumento di outreach, potresti dover pulire i domini, eliminare i duplicati, uniformare i ruoli o arricchire i dati aziendali.

Per i workflow correlati, consulta questi metodi di bulk enrichment.

Quando scegliere Custom Waterfall invece del waterfall predefinito

Usa Custom Waterfall quando vuoi avere il controllo.

È particolarmente adatto se:

• Paghi già uno o più strumenti di email finder.
• Hai crediti inutilizzati presso provider esterni.
• Vuoi testare l’ordine dei provider in base al mercato o alla fonte dei lead.
• Il tuo ICP ottiene risultati migliori con un provider specifico.
• Il costo per email trovata è più importante di una configurazione gestita.
• Vuoi che Datablist gestisca la sequenza dei provider e i nuovi tentativi in caso di rate limit, mantenendo il controllo delle chiavi API.

Usa il waterfall predefinito di Datablist se preferisci una configurazione più semplice. Se non vuoi gestire account dei provider, chiavi API, quote esterne e fatturazione, l’opzione gestita è più immediata. Datablist controlla la sequenza e addebita 25 crediti Datablist per ogni email di lavoro trovata.

Nessuna delle due opzioni è sempre migliore. Sceglierei la modalità predefinita per la rapidità e quella personalizzata per fare esperimenti sui costi, sfruttare abbonamenti esistenti o controllare meglio la sequenza.

Varianti comuni

Export di lead con nome completo

Alcuni export contengono un’unica colonna Full Name invece di colonne separate per nome e cognome. In questo caso, attiva Use Full Name nelle impostazioni di Email Finder e mappa la colonna con il nome completo.

Quando possibile, continuo a preferire campi separati, ma non bloccherei il workflow solo perché il file contiene un’unica colonna per il nome.

Liste basate sui domini

Se la lista contiene i domini, usali. Mappa Company Domain su Company Name or Domain e conserva Company Name come informazione di contesto.

È la configurazione più pulita per la maggior parte delle liste di lead B2B, perché i domini riducono le ambiguità.

Liste con il solo nome dell’azienda

Se la lista contiene nomi di persone e aziende ma non i domini, mappa Company Name su Company Name or Domain. Datablist consulta i propri dataset aziendali, verifica i possibili siti web e passa un dominio accettato al waterfall personalizzato. Se il resolver non riesce a selezionare un dominio affidabile, i provider compatibili possono comunque ricevere il nome originale dell’azienda.

Non devi eseguire prima Company Name to Domain, a meno che tu non voglia ottenere anche il dominio risolto in una colonna di output.

Liste ricche di profili LinkedIn

Se il file contiene URL standard dei profili LinkedIn, mappali come contesto facoltativo in questo workflow.

Se gli URL dei profili LinkedIn sono l’unico input affidabile a tua disposizione, valuta il metodo separato By LinkedIn URL di Email Finder. La sequenza personalizzata descritta in questo articolo viene configurata con il metodo By Name and Company.

Workflow per agenzie

Per le attività di un’agenzia, terrei separate le liste dei clienti usando collection o campi di origine distinti. Testa la sequenza dei provider in ciascun mercato prima di applicarla su larga scala.

Una sequenza efficace per i founder di SaaS statunitensi potrebbe non offrire gli stessi risultati con aziende retail francesi o imprese industriali tedesche.

Risoluzione dei problemi

missing_source_data

Controlla che la riga contenga un nome e un input aziendale utilizzabili. Con il metodo predefinito, Datablist richiede nome e cognome, a meno che Use Full Name non sia attivo, oltre al nome o al dominio dell’azienda.

invalid_data

Cerca domini, siti web, nomi o URL LinkedIn malformati. Spesso il problema deriva da export disordinati in cui la colonna del sito web contiene note, URL di tracking o valori segnaposto vuoti.

not_found

Nessun provider della sequenza ha restituito un’email per la riga. Puoi correggere l’input, provare un’altra sequenza o lasciare vuoto il campo email. Non dare per scontato che ogni contatto abbia un indirizzo di lavoro reperibile.

Errori del provider o della chiave API

Datablist riprova in caso di risposte temporanee dovute ai rate limit durante le esecuzioni personalizzate, ma gli errori persistenti del provider richiedono comunque un intervento. Controlla la chiave, lo stato dell’account, l’accesso alle API, la quota giornaliera e la situazione dei pagamenti nell’account del provider esterno.

Troppi risultati unverified

Rivedi l’ordine dei provider. Se il primo restituisce molte email non verificate, prova a spostarlo più avanti o a testare un altro provider iniziale. Preferisco avere meno email utili anziché una lista più ampia con un elevato rischio per la deliverability.

Conclusione

Un waterfall email finder personalizzato è utile quando vuoi affidare a Datablist la sequenza dei provider, la gestione dei rate limit temporanei e la verifica dei risultati, mantenendo al tempo stesso il controllo delle chiavi API.

Il workflow è semplice: importa la lista di lead, attiva Custom Waterfall, aggiungi le righe con provider e chiavi API, mappa input e output, esegui un’anteprima, elabora la lista, controlla gli stati e infine esporta i dati o continua ad arricchirli.

Inizia in piccolo. Usa due o tre provider, testa un gruppo limitato di righe e confronta Email Status con Finder Provider prima di spendere i crediti esterni sull’intera lista.

FAQ

Che cos’è un waterfall email finder personalizzato?

Un waterfall email finder personalizzato è una ricerca di email basata su più provider, nella quale scegli la sequenza e autentichi ogni servizio con la tua chiave API. Ogni riga viene verificata dai provider nell’ordine stabilito finché non viene trovata un’email o la sequenza non termina.

Posso usare le mie chiavi API per Email Finder in Datablist?

Sì. Nel Waterfall Email Finder di Datablist, attiva Custom Waterfall mentre utilizzi il metodo By Name and Company. Aggiungi quindi una riga per ogni provider e incolla la relativa chiave API.

Datablist addebita crediti con Custom Waterfall?

Datablist considera le esecuzioni valide con chiavi API personalizzate come operazioni senza costi in crediti Datablist. I provider esterni di email finder possono comunque addebitare i costi tramite account, piani, tariffe API o sistemi di crediti propri.

Datablist riprova in caso di rate limit con Custom Waterfall?

Sì. Datablist gestisce le risposte temporanee dovute ai rate limit durante le esecuzioni di Custom Waterfall, evitando che un rallentamento momentaneo del provider causi subito l’errore della riga. Servono comunque account validi, chiavi API funzionanti e una quota sufficiente in ogni strumento esterno.

Quali provider posso usare in un Custom Waterfall?

I provider personalizzati supportati sono Icypeas, Enrow, Prospeo, Wiza, Findymail, LeadMagic, TryKitt, Enrich.so e FullEnrich.

Quali input servono?

Per il metodo By Name and Company, usa nome e cognome oppure un’unica colonna con il nome completo quando Use Full Name è attivo. Serve anche un campo con il nome o il dominio dell’azienda. Il dominio è l’input più pulito, ma Datablist può individuare internamente un dominio probabile quando fornisci il nome aziendale. Se disponibile, puoi mappare anche l’URL standard del profilo LinkedIn.

Posso usare solo gli URL dei profili LinkedIn?

Datablist offre un metodo separato, By LinkedIn URL, per gli URL standard dei profili LinkedIn. La sequenza Custom Waterfall descritta in questa guida viene configurata con il metodo By Name and Company.

Che cosa indica l’output Provider?

L’output Provider mostra quale provider personalizzato ha restituito l’email. Di solito rinomino questa colonna di output in Finder Provider, così risulta più chiara nella lista finale dei lead.

Conviene mettere per primo il provider più economico?

Spesso sì, ma non sempre. Confronta costo esterno, copertura, qualità e regole di fatturazione del provider. Un servizio più economico è utile solo se restituisce email di cui puoi fidarti.