> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API di validazione email

> Migliora la deliverability e mantieni sane le tue mailing list con l'API di validazione email di Cleariflow, tra le migliori del settore.

## Avvio rapido

Per effettuare una richiesta, fornisci il tuo `api_key` univoco e l'`email` da verificare — non serve altro:

```bash theme={"system"}
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:

<ResponseExample>
  ```json theme={"system"}
  {
    "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"
    }
  }
  ```
</ResponseExample>

### Parametri della richiesta

<ParamField query="api_key" type="string" required>
  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.
</ParamField>

<ParamField query="email" type="String" required>
  L'indirizzo email da verificare.
</ParamField>

<ParamField query="auto_correct" type="Boolean">
  Flag opzionale per disabilitare l'autocorrezione. Imposta `auto_correct=false` per
  disattivarla. È abilitata per impostazione predefinita.
</ParamField>

### Parametri della risposta

Le risposte vengono restituite in un [JSON](https://www.json.org/json-en.html) compatto e standardizzato.

<ResponseField name="email" type="String">
  Ripete l'`email` inviata nella richiesta.
</ResponseField>

<ResponseField name="auto_correct" type="String">
  Correzione suggerita quando viene rilevato un probabile errore di battitura (es.
  [johnsmith@gmial.com](mailto:johnsmith@gmial.com) => [johnsmith@gmail.com](mailto:johnsmith@gmail.com)). Vuoto se non c'è alcun suggerimento.
</ResponseField>

<ResponseField name="deliverability" type="String">
  Valutazione di Cleariflow sulla capacità dell'indirizzo di ricevere posta. Valori
  possibili: `DELIVERABLE`, `UNDELIVERABLE`, `UNKNOWN`. `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`. Tutti i piani eseguono gli
  stessi controlli; i gratuiti differiscono solo per quota mensile e limiti di frequenza
  (vedi codici 422 e 429).
</ResponseField>

<ResponseField name="quality_score" type="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`.
</ResponseField>

<ResponseField name="is_valid_format" type="Boolean">
  `true` quando l'indirizzo corrisponde al pattern standard `local@domain.tld`.
  Elementi mancanti o caratteri non validi restituiscono `false`.
</ResponseField>

<ResponseField name="is_free_email" type="Boolean">
  `true` se il dominio appartiene a un provider di email gratuito (es. Gmail, Yahoo).
</ResponseField>

<ResponseField name="is_disposable_email" type="Boolean">
  `true` se il dominio è nella nostra lista di provider di caselle temporanee o usa e getta
  (es. Mailinator, Yopmail).
</ResponseField>

<ResponseField name="is_role_email" type="Boolean">
  `true` se la parte locale sembra un account di ruolo piuttosto che di un individuo,
  ad es. `team@`, `sales@`, `info@`.
</ResponseField>

<ResponseField name="is_catchall_email" type="Boolean">
  `true` se il dominio è configurato come
  [catch-all](https://www.corporatecomm.com/faqs/other-questions/what-is-a-catch-all-account).
</ResponseField>

<ResponseField name="is_mx_found" type="Boolean">
  `true` quando esistono [record MX](https://en.wikipedia.org/wiki/MX_record) per il
  dominio.
</ResponseField>

<ResponseField name="is_smtp_valid" type="Boolean">
  `true` se la verifica
  [SMTP](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol) 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.
</ResponseField>

## 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.

```bash theme={"system"}
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = johnsmith@gmial.con
```

Una risposta di successo ha questo aspetto:

```json theme={"system"}
{
  "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": false,
    "text": "FALSE"
  },
  "is_mx_found": {
    "value": false,
    "text": "FALSE"
  },
  "is_smtp_valid": {
    "value": false,
    "text": "FALSE"
  }
}
```

### 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`.

```bash theme={"system"}
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = johnsmith
```

Una risposta di successo ha questo aspetto:

```json theme={"system"}
{
  "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.

| Code | Type                  | Details                                                                                |
| ---- | --------------------- | -------------------------------------------------------------------------------------- |
| 200  | OK                    | Richiesta completata con successo.                                                     |
| 400  | Bad request           | Richiesta malformata o non valida.                                                     |
| 401  | Unauthorized          | Autenticazione fallita — di solito chiave API mancante o non valida.                   |
| 422  | Quota reached         | Quota esaurita (es. crediti insufficienti sui piani gratuiti).                         |
| 429  | Too many requests     | Limite di frequenza superato (i piani gratuiti consentono fino a 1 richiesta/secondo). |
| 500  | Internal server error | Errore imprevisto dal nostro lato.                                                     |
| 503  | Service unavailable   | Servizio temporaneamente non disponibile.                                              |

## Altre note

Nota sui piani: tutti i piani (gratuiti e a pagamento) eseguono gli stessi controlli, inclusi MX, SMTP e rilevamento catch-all.

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.