Vai al contenuto principale
GET
/
v1
API di validazione email
curl --request GET \
  --url https://emailvalidation.cleariflow.com/v1
{
  "email": "jane.doe@acme-corp.com",
  "autocorrect": "",
  "deliverability": "DELIVERABLE",
  "quality_score": 0.85,
  "is_valid_format": {
    "value": true,
    "text": "TRUE"
  },
  "is_free_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_disposable_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_role_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_catchall_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_mx_found": {
    "value": true,
    "text": "TRUE"
  },
  "is_smtp_valid": {
    "value": true,
    "text": "TRUE"
  }
}

​
Avvio rapido

Per effettuare una richiesta, fornisci il tuo api_key univoco e l’email da verificare — non serve altro: 
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = jane.doe@acme-corp.com
In caso di successo, la richiesta restituisce tutte le informazioni disponibili sull’indirizzo: 
{
  "email": "jane.doe@acme-corp.com",
  "autocorrect": "",
  "deliverability": "DELIVERABLE",
  "quality_score": 0.85,
  "is_valid_format": {
    "value": true,
    "text": "TRUE"
  },
  "is_free_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_disposable_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_role_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_catchall_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_mx_found": {
    "value": true,
    "text": "TRUE"
  },
  "is_smtp_valid": {
    "value": true,
    "text": "TRUE"
  }
}

​
Parametri della richiesta

​
api_key
string
obbligatorio
Le tue credenziali API personali. Le chiavi sono limitate per prodotto Cleariflow, quindi una chiave di validazione email non autorizza richieste ad altre API, ad esempio la geolocalizzazione IP.
​
email
String
obbligatorio
L’indirizzo email da verificare.
​
auto_correct
Boolean
Flag opzionale per disabilitare l’autocorrezione. Imposta auto_correct=false per disattivarla. È abilitata per impostazione predefinita.

​
Parametri della risposta

Le risposte vengono restituite in un JSON compatto e standardizzato.
​
email
String
Ripete l’email inviata nella richiesta.
​
auto_correct
String
Correzione suggerita quando viene rilevato un probabile errore di battitura (es. johnsmith@gmial.com => johnsmith@gmail.com). Vuoto se non c’è alcun suggerimento.
​
deliverability
String
Valutazione di Cleariflow sulla capacità dell’indirizzo di ricevere posta. Valori possibili: DELIVERABLE, UNDELIVERABLE, UNKNOWN. Nei piani a pagamento, DELIVERABLE richiede un controllo SMTP riuscito; se esistono record MX ma SMTP non può confermare la casella (comune con i grandi provider), il risultato è UNKNOWN. Nei piani gratuiti il valore è UNKNOWN salvo indirizzi chiaramente non consegnabili (formato non valido o dominio disposable).
​
quality_score
Float
Punteggio decimale da 0 a 0.99 che riflette la qualità dell’indirizzo. Gli indirizzi disposable sono limitati a circa 0.05; senza conferma SMTP, massimo 0.55.
​
is_valid_format
Boolean
true quando l’indirizzo corrisponde al pattern standard local@domain.tld. Elementi mancanti o caratteri non validi restituiscono false.
​
is_free_email
Boolean
true se il dominio appartiene a un provider di email gratuito (es. Gmail, Yahoo).
​
is_disposable_email
Boolean
true se il dominio è nella nostra lista di provider di caselle temporanee o usa e getta (es. Mailinator, Yopmail).
​
is_role_email
Boolean
true se la parte locale sembra un account di ruolo piuttosto che di un individuo, ad es. team@, sales@, info@.
​
is_catchall_email
Boolean
true se il dominio è configurato come catch-all. Disponibile solo sui piani a pagamento; sui piani gratuiti restituisce null/UNKNOWN.
​
is_mx_found
Boolean
true quando esistono record MX per il dominio. Disponibile solo sui piani a pagamento; sui piani gratuiti restituisce null/UNKNOWN.
​
is_smtp_valid
Boolean
true se la verifica SMTP ha esito positivo. Se SMTP fallisce ma altri controlli passano, il risultato può essere UNKNOWN. Sconsigliamo di bloccare registrazioni o invii di moduli basandosi solo su errori SMTP. Disponibile solo sui piani a pagamento; sui piani gratuiti restituisce null/UNKNOWN.

​
Esempi di richiesta

​
Esempio: probabile errore di battitura

Questo esempio mostra una richiesta in cui viene rilevato un probabile errore di battitura nell’indirizzo inviato. Anche quando viene trovato un probabile errore di battitura, tutti gli altri controlli (es. email gratuita, dominio usa e getta) vengono eseguiti sull’indirizzo originariamente inviato — non sulla correzione suggerita. 
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = johnsmith@gmial.con
Una risposta di successo ha questo aspetto: 
{
  "email": "johnsmith@gmial.con",
  "autocorrect": "johnsmith@gmail.com",
  "deliverability": "UNKNOWN",
  "quality_score": 0.4,
  "is_valid_format": {
    "value": true,
    "text": "TRUE"
  },
  "is_free_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_disposable_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_role_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_catchall_email": {
    "value": null,
    "text": "UNKNOWN"
  },
  "is_mx_found": {
    "value": null,
    "text": "UNKNOWN"
  },
  "is_smtp_valid": {
    "value": null,
    "text": "UNKNOWN"
  }
}

​
Esempio: formato non valido

Questo esempio mostra un indirizzo che non supera la formattazione di base. Quando is_valid_format è false, i controlli successivi (es. is_free_email, is_role_email) vengono saltati e segnalati come false. 
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = johnsmith
Una risposta di successo ha questo aspetto: 
{
  "email": "johnsmith",
  "autocorrect": "",
  "deliverability": "UNDELIVERABLE",
  "quality_score": 0.0,
  "is_valid_format": {
    "value": false,
    "text": "FALSE"
  },
  "is_free_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_disposable_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_role_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_catchall_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_mx_found": {
    "value": false,
    "text": "FALSE"
  },
  "is_smtp_valid": {
    "value": false,
    "text": "FALSE"
  }
}

​
Caricamento massivo (CSV)

Preferisci non chiamare l’API direttamente? Usa il caricamento massivo CSV — i risultati ti verranno inviati via email al termine dell’elaborazione. Durante il caricamento di un CSV, segui queste linee guida:
  • Inserisci gli indirizzi email nella prima colonna.
  • Elimina le righe vuote.
  • Usa un indirizzo per riga.
  • Limita i file a un massimo di 50.000 righe.

​
Codici di risposta ed errore

Gli errori vengono restituiti in JSON con un codice e una descrizione leggibile. I codici più comuni sono elencati di seguito.
CodeTypeDetails
200OKRichiesta completata con successo.
400Bad requestRichiesta malformata o non valida.
401UnauthorizedAutenticazione fallita — di solito chiave API mancante o non valida.
422Quota reachedQuota esaurita (es. crediti insufficienti sui piani gratuiti).
429Too many requestsLimite di frequenza superato (i piani gratuiti consentono fino a 1 richiesta/secondo).
500Internal server errorErrore imprevisto dal nostro lato.
503Service unavailableServizio temporaneamente non disponibile.

​
Altre note

Nota sulla fatturazione: ogni email valutata consuma un credito per richiesta — indipendentemente dall’esito. L’invio di un indirizzo non valido (es. “fda3346ds”) conta comunque come un credito.