Skip to content

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 faCosto
BaseFormato, dominio, record MX e risultati che già conosciamoIncluso in ogni piano
AvanzatoControlla anche la casella sul server di destinazioneUn 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.

ValoreComportamento
NEVERLa casella non viene mai sondata; viene eseguito solo il controllo di base
UNKNOWN_ONLYViene sondato solo ciò che non è già controllato e aggiornato
ALWAYSSondata 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.

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

RisultatoCosa significa
catch_allIl dominio accetta qualsiasi indirizzo, quindi la casella non si può confermare
riskyL'indirizzo esiste ma mostra segni di bassa qualità o di spam trap
unknownIl 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.

json
{
  "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"
  }
}
CampoValoriDescrizione
modeunknown_only, alwaysQuando viene sondata la casella
levelpreventive, restrictiveQuanto è esigente
blocklista di catch_all, risky, unknownRisultati 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 dominioValore nella richiestaEffetto
Controllo avanzato NEVER(non disponibile)Una richiesta può solo rendere più rigoroso, mai disattivare
Controllo avanzato UNKNOWN_ONLYmode: "unknown_only"Sonda solo ciò che non è già controllato
Controllo avanzato ALWAYSmode: "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 bloccatiblock: ["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}
json
{
  "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"
    }
  }
}
CampoDescrizione
checkedUn risultato di validazione è già disponibile
pendingÈ stato segnato per il controllo e l'invio non l'ha ancora validato
advancedIl controllo ha sondato la casella. Descrive la portata tecnica, non l'addebito
reusedIl risultato ha riutilizzato un tuo controllo ancora valido, senza spendere crediti
classificationvalid, catch_all, risky, unknown o invalid. null se non ancora controllato
reasonMotivo leggibile restituito dal validatore. null se non ancora controllato
reason_codeCodice stabile del motivo. null se non ancora controllato
checked_atData 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.

Built with VitePress