Validazione dei destinatari
Prima di consegnare un'email, Mailiqo controlla che il destinatario esista e sia raggiungibile. Questo protegge la tua reputazione di mittente: ogni bounce la danneggia, e una reputazione scarsa manda le tue email nello spam anche quando sono legittime.
Ci sono due livelli di controllo:
| Cosa fa | Costo | |
|---|---|---|
| Base | Formato, dominio, record MX e risultati che già conosciamo | Incluso in ogni piano |
| Avanzato | Controlla anche la casella sul server di destinazione | Un credito per ogni nuovo controllo; riutilizzare un risultato valido è gratis |
Se esaurisci i crediti l'invio non viene bloccato: i destinatari rimanenti vengono controllati con la validazione di base.
Da dove viene la configurazione
La configurazione sta su ogni dominio di invio, e la imposti nel pannello, nella scheda Deliverability del dominio. Si applica allo stesso modo all'API, all'SMTP e agli invii dal pannello.
Cosa viene sempre controllato
Il formato dell'indirizzo, i record MX del dominio e il risultato dei controlli precedenti si applicano a ogni invio, qualunque sia la configurazione: proteggono la tua reputazione e non si possono disattivare. Quello che configuri qui sotto è quanto in profondità arriva il controllo e quanto è severa la decisione.
Ha tre parti:
Controllo avanzato — quando la casella viene sondata sul server di destinazione. È la parte che usa un credito di validazione.
| Valore | Comportamento |
|---|---|
NEVER | La casella non viene mai sondata; viene eseguito solo il controllo di base |
UNKNOWN_ONLY | Viene sondato solo ciò che non è già controllato e aggiornato |
ALWAYS | Sondata a ogni invio, senza riutilizzare controlli precedenti |
Solo un controllo avanzato segna un destinatario come conosciuto: uno di base non conferma la casella, quindi non risparmia il sondaggio.
Rigore — quali risultati vengono accettati per procedere.
| Valore | Comportamento |
|---|---|
SOFT (preventivo) | Scarta gli indirizzi non validi e qualsiasi risultato dubbio che hai segnato da bloccare |
STRICT (restrittivo) | Vengono accettati solo i destinatari confermati come validi |
Risultati bloccati — quali casi dubbi vuoi scartare quando il livello è preventivo. Per impostazione predefinita non viene bloccato nulla: un risultato dubbio viene comunque inviato. Spunta solo ciò che preferisci scartare.
| Risultato | Cosa significa |
|---|---|
catch_all | Il dominio accetta qualsiasi indirizzo, quindi la casella non si può confermare |
risky | L'indirizzo esiste ma mostra segni di bassa qualità o di spam trap |
unknown | Il server di destinazione non ha risposto in tempo |
Tutto ciò che è invalid viene sempre scartato, qualunque sia la configurazione.
Regolare la validazione per un singolo invio
Se un invio richiede più attenzione del solito — una conferma d'ordine, una reimpostazione della password — puoi regolarlo nella richiesta stessa con l'oggetto validation. È facoltativo: senza di esso si applica la configurazione del dominio.
Dove si usa
L'oggetto validation e force_validation sono accettati su entrambi gli endpoint di invio: POST /mailing/send e POST /mailing/send-template.
Non esiste un equivalente SMTP: gli invii SMTP usano sempre la configurazione del dominio. E se quello che vuoi è controllare indirizzi senza inviare loro nulla, stai cercando l' API di validazione.
{
"from": "[email protected]",
"to": "[email protected]",
"subject": "Conferma il tuo ordine",
"body_html": "<p>Grazie per il tuo acquisto.</p>",
"validation": {
"mode": "always",
"level": "restrictive"
}
}| Campo | Valori | Descrizione |
|---|---|---|
mode | unknown_only, always | Quando viene sondata la casella |
level | preventive, restrictive | Quanto è esigente |
block | lista di catch_all, risky, unknown | Risultati dubbi che scarti per questo invio |
Come corrisponde alla configurazione del dominio
Il pannello e la richiesta chiamano le stesse cose in due modi diversi. Questa tabella li unisce:
| Configurazione del dominio | Valore nella richiesta | Effetto |
|---|---|---|
Controllo avanzato NEVER | (non disponibile) | Una richiesta può solo rendere più rigoroso, mai disattivare |
Controllo avanzato UNKNOWN_ONLY | mode: "unknown_only" | Sonda solo ciò che non è già controllato |
Controllo avanzato ALWAYS | mode: "always" | Sonda a ogni invio |
Rigore SOFT (preventivo) | level: "preventive" | Scarta gli indirizzi non validi e ciò che imposti in block |
Rigore STRICT (restrittivo) | level: "restrictive" | Accetta solo i destinatari confermati come validi |
| Risultati bloccati | block: ["catch_all", "risky", "unknown"] | Si aggiungono a ciò che il dominio già blocca |
I valori non distinguono tra maiuscole e minuscole. Per compatibilità, soft e strict sono accettati anche in entrambi i campi, ma non significano la stessa cosa in ciascuno (mode: "strict" equivale a always, mentre level: "strict" equivale a restrictive). Usa unknown_only/always e preventive/restrictive, che non sono ambigui.
Un invio può solo rendere più rigoroso
La regolazione non allenta mai la configurazione del dominio. Se il tuo dominio sonda già a ogni invio e la richiesta chiede unknown_only, resta always. E block si aggiunge soltanto: se il tuo dominio blocca già risky, un invio non può togliere quel blocco omettendolo.
Per questo never non viene accettato dalla richiesta: un invio può chiedere più controllo, mai meno.
Un valore non riconosciuto restituisce 400 con il codice 1419.
force_validation
force_validation: true esegue un nuovo controllo su ogni destinatario durante l'invio, invece di risolverlo con un risultato precedente. È la scorciatoia per validation.mode: "always", quindi spende un credito per destinatario controllato.
Non cambia quanto è esigente il controllo: forzare un controllo non allenta mai la politica di invio. E se non hai più crediti l'invio non viene bloccato: il controllo sarà di base, e il risultato lo indica con advanced: false.
Una riconsegna tecnica dello stesso invio non controlla né addebita di nuovo: viene recuperato il risultato che quell'operazione ha già salvato.
Leggere il risultato
La validazione avanzata avviene durante l'invio, dopo che l'API ti ha già risposto. Per questo la risposta di POST /send non contiene risultati per destinatario: quando la ricevi, il controllo non è ancora avvenuto.
Quello che la risposta restituisce sono i destinatari scartati prima dell'accodamento, in rejected_recipients, con il loro motivo: formato errato, oppure un risultato precedente che la tua configurazione non accetta.
Il risultato completo sta nel dettaglio di ogni destinatario:
GET /v1/mailing/email-message/{uuid}{
"status": "success",
"data": {
"uuid": "9f1c...",
"recipient_email": "[email protected]",
"status": "rejected",
"validation": {
"checked": true,
"pending": false,
"advanced": true,
"reused": false,
"classification": "catch_all",
"reason": "Mailbox not verifiable",
"reason_code": "mailbox_not_verifiable",
"checked_at": "2026-01-01T10:29:07+00:00"
}
}
}| Campo | Descrizione |
|---|---|
checked | Un risultato di validazione è già disponibile |
pending | È stato segnato per il controllo e l'invio non l'ha ancora validato |
advanced | Il controllo ha sondato la casella. Descrive la portata tecnica, non l'addebito |
reused | Il risultato ha riutilizzato un tuo controllo ancora valido, senza spendere crediti |
classification | valid, catch_all, risky, unknown o invalid. null se non ancora controllato |
reason | Motivo leggibile restituito dal validatore. null se non ancora controllato |
reason_code | Codice stabile del motivo. null se non ancora controllato |
checked_at | Data del controllo, non dell'invio: riutilizzare un risultato precedente non la rinnova |
L'oggetto validation è sempre presente. Quando non c'è ancora un risultato, checked è false e i campi del risultato tornano null.
Quando la validazione scarta un destinatario, il suo status diventa rejected e il motivo compare anche in error_message.
Ottieni lo UUID di ogni destinatario da email_messages chiamando GET /email-request/{uuid}. Consulta ciascuno con GET /email-message/{uuid} per leggere il suo blocco validation: se è ancora pending, cosa è stato checked, e se il controllo è stato advanced.
Crediti di validazione
Ti viene addebitata l'esecuzione di un nuovo controllo avanzato, qualunque sia il canale: API di invio, SMTP, API di validazione o pannello. Consultare o riutilizzare un tuo controllo ancora valido non spende altri crediti, e il controllo di base non ne spende mai.
Un controllo eseguito viene addebitato anche se conclude che l'indirizzo non è valido o lascia il risultato come unknown: paghi il controllo, non il verdetto. Se un errore interno gli impedisce di completarsi, il credito viene restituito.
I crediti arrivano da due fonti:
- Inclusi nel tuo piano: si rinnovano ogni mese e scadono alla chiusura del ciclo.
- Acquistati in pacchetti: scadono 12 mesi dopo l'acquisto.
Vengono sempre usati prima quelli che scadono prima, quindi i crediti del piano si spendono prima di quelli acquistati. Puoi controllare il saldo e comprare pacchetti dal pannello, e attivare la ricarica automatica in modo che venga acquistato un pacchetto quando il saldo scende sotto il minimo che imposti.
Se chiedi la validazione avanzata su un invio e sei senza crediti, l'invio non viene bloccato: il controllo ricade su quello di base e il risultato lo segnala con validation.advanced a false. Sull'API di validazione, esaurire i crediti rifiuta invece la richiesta.
