Verifica email in blocco API: un flusso di lavoro pratico per i job batch

Verifica email in blocco API: un flusso di lavoro pratico per i job batch

La domanda: hai un lungo elenco di indirizzi nel tuo sistema. Come lo invii tramite l'API di FairValid in batch, gestendo gli errori in modo sicuro e rileggendo i risultati senza perdere traccia dei crediti?

Risposta breve: inizia nella sandbox con una chiave Test. Poi suddividi l'elenco in job fino a 5.000 indirizzi e assegna a ciascun job una propria chiave di idempotenza. Invia ogni job con una chiave Live, controllane lo stato e scorri i risultati per pagine in base all'esito. Tieni distinte tre situazioni: verifiche in sospeso, errori tecnici e risultati Sconosciuto.

Dati verificati il 13 novembre 2026 sulla base del riferimento API, della guida ai risultati e delle regole sui crediti di FairValid.

Passaggio 1: sviluppa prima sulla sandbox

Il riferimento API indica di creare una chiave Test in Chiavi API, di conservarla sul tuo server e di impostarla nel tuo ambiente insieme all'URL di base. Le chiavi Test funzionano con indirizzi riservati sul dominio example.com. Non effettuano chiamate ai provider e non consumano crediti. Le chiavi Test accedono ai propri job simulati.

I job di test restituiscono stati deterministici: completato, in sospeso, non riuscito o annullato. Consulta il riferimento API per gli indirizzi sandbox esatti e usali per verificare che il tuo codice gestisca questi stati. Questi casi mostrano solo gli esiti per cui sono stati progettati. Non coprono ogni ramo della tua integrazione, quindi verifica separatamente i tuoi percorsi di errore.

Passaggio 2: passa a una chiave Live con gli ambiti corretti

Per la produzione, il riferimento API indica che per creare job serve una chiave Live con ambito submit. Aggiungi l'ambito read per leggere lo stato dei job e i risultati. Le chiavi Live possono avere anche un ambito balance. I segreti completi delle chiavi vengono mostrati una sola volta, quindi conservali in modo sicuro sul tuo server al momento della creazione. Una chiave revocata blocca le nuove richieste.

I job Live usano la coda di verifica e il saldo crediti del tuo workspace. Restano validi gli ambiti delle chiavi, i limiti di spesa delle chiavi, l'accesso al workspace e i limiti di elaborazione. Una chiave Live non ti dà accesso illimitato.

Passaggio 3: suddividi l'elenco e invia i job

Ogni job accetta da 1 a 5.000 indirizzi in JSON, fino a 2 MiB. Ecco un approccio pratico:

1. Suddividi l'elenco in blocchi. A titolo di esempio, 12.000 indirizzi diventerebbero tre job da 5.000, 5.000 e 2.000.
2. Assegna a ciascun blocco una propria Idempotency-Key stabile e registra quali delle tue righe sono finite in quale blocco. Mantenere questa corrispondenza dalla tua parte rende più semplice ricollegare i risultati ai tuoi record.
3. Invia all'endpoint dei job. Un nuovo job restituisce HTTP 202 con un job_id UUID. Un nuovo tentativo corrispondente restituisce HTTP 200 con lo stesso job. Ciò significa che, dopo un timeout, puoi reinviare la stessa richiesta con la stessa chiave e ottenere il job esistente.

Passaggio 4: gestisci i due errori che sembrano simili

Entrambe queste risposte possono bloccare un invio, ma hanno significati diversi:

• HTTP 503 live_verification_unavailable può essere restituito durante una pausa operativa. Secondo il riferimento API, in questo caso non vengono trattenuti crediti. Riprova più tardi con la stessa Idempotency-Key.
• HTTP 402 key_cap_reached significa che una nuova richiesta supererebbe il limite di spesa complessivo della chiave. Tale limite conteggia i crediti già addebitati più quelli riservati per le identità univoche accettate. Non viene creato alcun job né alcuna trattenuta. Un limite complessivo non si ricarica nel tempo, quindi attendere non risolve il problema. Rivedi il limite della chiave nelle impostazioni delle chiavi API, oppure usa una chiave con un limite residuo sufficiente per il lavoro. Inoltre, il limite di una chiave non può aggiungere crediti al workspace: limita solo ciò che quella chiave può spendere.

Registra queste due risposte separatamente dagli errori di autorizzazione e dai limiti di elaborazione, così che la persona giusta riceva l'avviso giusto.

Passaggio 5: monitora lo stato del job, poi scorri i risultati per pagine

L'endpoint del job restituisce lo stato attuale e il riepilogo di un job. Lo stato può essere in coda, in esecuzione, in pausa, in annullamento, annullato o completato. Se richiedi l'annullamento, il lavoro già in corso potrebbe comunque concludersi.

L'endpoint dei risultati restituisce fino a 50 risultati alla volta, insieme a un next_cursor firmato. Passa quel valore come parametro di query cursor: mantiene il filtro e la ricerca originali. I filtri sono all, valid, invalid, catch_all, unknown, still_checking e not_checked. Puoi usarli per recuperare solo le righe che richiedono una decisione, ad esempio tutte quelle contrassegnate come sconosciute.

Passaggio 6: trasforma gli esiti in decisioni

La guida ai risultati descrive i risultati come elementi di valutazione, non come garanzia di consegna:

• Valido indica una verifica positiva utilizzabile. Non garantisce mai la consegna in casella.
• Non valido significa che l'indirizzo non ha superato la verifica.
• Catch-all significa che il dominio potrebbe accettare molti indirizzi, quindi una conclusione sulla specifica casella potrebbe essere meno certa. Leggi i dettagli prima di usare l'indirizzo.
• Sconosciuto significa che la verifica non ha potuto fornire una risposta affidabile.
• Verifica in corso significa che non c'è ancora una risposta definitiva. Continua a interrogare lo stato e non trattarlo come Sconosciuto.

Gli errori tecnici e gli elementi non elaborati costituiscono una categoria a parte. Le regole sui crediti di FairValid specificano che non vengono riclassificati come Sconosciuto.

Passaggio 7: comprendi le riserve di crediti

Il riferimento API indica che i crediti del workspace vengono riservati man mano che le verifiche vengono ammesse all'elaborazione. I risultati seguono le stesse regole di addebito e restituzione della dashboard. In base alle regole sui crediti, un risultato Valido o Non valido completato costa un credito. I risultati Sconosciuto e Catch-all non risolti non comportano alcuna detrazione finale di crediti, perché i crediti trattenuti vengono svincolati o restituiti. In sospeso non è un risultato definitivo. Anche gli errori tecnici e il lavoro non elaborato non comportano alcuna detrazione finale di crediti. I crediti restituiti mantengono il lotto e le regole di scadenza originari.

L'endpoint del saldo riporta i crediti disponibili e trattenuti per il workspace live. Quando il campo free_allowance_held è true, la quota gratuita è sospesa e non viene conteggiata in available_credits né in free_available. I crediti a pagamento restano disponibili. L'account originale riceve 300 crediti gratuiti ogni mese alla data di registrazione e i crediti gratuiti non utilizzati non vengono riportati al mese successivo. I workspace aggiuntivi non ricevono una quota gratuita in più. I crediti gratuiti vengono usati per primi e i crediti a pagamento non scadono finché l'account resta aperto.

Una semplice checklist

• Esegui i test con una chiave Test e i casi sandbox documentati.
• Usa una chiave Live con ambiti submit e read e un limite adeguato al lavoro previsto.
• Mantieni ogni blocco entro 5.000 indirizzi, con una chiave di idempotenza stabile per ciascun blocco.
• In caso di 503, riprova più tardi con la stessa chiave. In caso di 402, non aspettare: intervieni sul limite.
• Scorri i risultati per pagine con il cursore firmato, filtrandoli per esito.
• Tieni distinti nei tuoi dati in sospeso, errore tecnico e Sconosciuto.

Se vuoi provare questo flusso di lavoro, puoi creare una chiave Test ed eseguire un job sandbox senza consumare crediti prima del tuo primo invio live. Il riferimento API contiene tutti i dettagli sugli endpoint.