Riferimento API REST di Email Verifier

L’API Email Verifier è disponibile sotto /api/v1. Usa l’host TrekMail impiegato dal tuo account per l’accesso. Gli esempi usano https://YOUR-TREKMAIL-HOST come segnaposto.

Autenticazione e scope

Passa un token API nell’header Authorization:

Authorization: Bearer YOUR_API_TOKEN

Abilita gli scope quando crei il token:

Assegna entrambi gli scope a un client che deve inviare un processo e poi leggerne o scaricarne il risultato.

Host e formato della richiesta

Tutti gli esempi usano corpi JSON e un token Bearer. Il caricamento file della dashboard è separato dall’API: POST /verify/bulk accetta un array JSON emails, non un file multipart. Usa esattamente l’host associato all’account e al token. Non presumere che token o saldo di un host brandizzato funzionino su un altro host.

Invia Content-Type: application/json per le richieste POST /verify e POST /verify/bulk. Conserva token e valore di idempotenza fuori dal codice lato client.

Idempotenza

POST /api/v1/verify/bulk e DELETE /api/v1/verify/bulk/{jobId} richiedono l’header Idempotency-Key. Genera un nuovo valore per ogni operazione prevista e riusalo solo per riprovare la stessa operazione.

Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee

La verifica singola e l’annullamento non richiedono questo header. Una richiesta collettiva è protetta anche dal rilevamento della stessa lista normalizzata e modalità entro 24 ore, ma la chiave di idempotenza resta il meccanismo corretto per riprovare.

Gestire un esito di rete incerto

Se l’applicazione perde la risposta a una richiesta collettiva, non generare un’altra chiave e non inviare un’altra lista. Ripeti la richiesta identica con la stessa chiave. Conserva la chiave con l’identificativo della lista di origine finché TrekMail non restituisce un ID processo. Così il nuovo tentativo resta collegato all’operazione originale ed evita un secondo addebito.

Riepilogo degli endpoint

Anteponi /api/v1 a ogni percorso della tabella.

Leggere il saldo crediti

GET /api/v1/verify/credits

Sull’host TrekMail standard, la risposta include la dotazione del piano e il saldo acquistato:

{
  "monthly_limit": 300,
  "monthly_used": 120,
  "monthly_remaining": 180,
  "purchased_balance": 5000,
  "total_available": 5180,
  "plan": "pro",
  "trialing": false,
  "resets_at": "2026-10-01T00:00:00+00:00"
}

Su un host White Label sono disponibili al prodotto brandizzato solo i crediti acquistati, quindi la risposta contiene purchased_balance e total_available.

Esempio di richiesta:

curl https://YOUR-TREKMAIL-HOST/api/v1/verify/credits \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Leggi il saldo subito prima di un invio grande. La risposta è un’istantanea: un’applicazione che invia più processi deve registrare l’importo addebitato in ogni risposta collettiva, invece di calcolarlo in seguito da un valore non aggiornato.

Campi del saldo

Le risposte White Label hanno intenzionalmente meno campi perché il prodotto brandizzato usa solo crediti acquistati.

Verificare un indirizzo

POST /api/v1/verify

{
  "email": "person@example.com",
  "mode": "quick"
}

La risposta include email, status, trust_score, checks, provider, risk_factors e credits_remaining. Sull’host standard, credits_remaining contiene i valori monthly e purchased. La struttura dettagliata di checks può cambiare in base alla modalità e alle informazioni rese disponibili dal provider ricevente.

Quick costa 1 credito. Deep normalmente costa 2 crediti, mentre le eccezioni specifiche del provider sono calcolate a 1 credito. Se la verifica non può essere eseguita dopo l’addebito, la richiesta singola rimborsa l’importo e restituisce una risposta di indisponibilità temporanea.

Esempio di richiesta:

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"person@example.com","mode":"quick"}'

Usa status, trust_score, provider e risk_factors di primo livello come normale contratto dell’applicazione. checks contiene utili elementi di supporto, ma le singole chiavi possono variare se un controllo a monte viene saltato, non è disponibile o Deep ottiene informazioni aggiuntive.

Interpretare un risultato singolo

Non fare in modo che l’applicazione consideri una risposta remota accettata una verifica di proprietà o autorizzazione. Mantieni separate le decisioni su iscrizione, rinuncia e preferenze di contatto.

Creare un processo collettivo

POST /api/v1/verify/bulk

{
  "emails": ["first@example.com", "second@example.net"],
  "name": "September contacts",
  "mode": "deep"
}

I duplicati vengono normalizzati prima del calcolo del prezzo. Un nuovo processo riuscito restituisce 201 con:

{
  "job_id": 42,
  "total": 2,
  "status": "pending",
  "rejected_count": 0,
  "rejected_sample": [],
  "credits_charged": 4,
  "breakdown": {"probe": 2, "skip": 0, "deep_savings": 0}
}

probe e skip spiegano il calcolo del prezzo Deep. deep_savings è la differenza rispetto all’addebito della tariffa Deep piena per ogni indirizzo inviato. Una lista duplicata restituisce job_id e stato esistenti invece di avviare un altro processo.

Esempio di richiesta:

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee" \
  -d '{"name":"September contacts","mode":"deep","emails":["first@example.com","second@example.net"]}'

Prima di accettare il processo, l’API verifica la sintassi email dei valori. Se tutte le voci vengono rifiutate, restituisce 422 e non crea un processo. Se ne rifiuta alcune, la risposta riuscita indica rejected_count e fino a cinque valori in rejected_sample. Non considerare questo piccolo campione un rapporto completo di pulizia; conserva il risultato di convalida della fonte nel tuo importatore.

Checklist per l’invio collettivo

1. Leggi e normalizza la fonte nella tua applicazione.
2. Limita la richiesta a 50,000 voci inviate.
3. Genera e conserva una chiave di idempotenza prima della richiesta.
4. Scegli un nome riconoscibile in seguito da un operatore.
5. Salva job_id, credits_charged e il dettaglio del prezzo restituito da TrekMail.
6. Esegui il polling del job_id salvato; non dedurre il completamento dalla richiesta HTTP originale.

Leggere un processo

GET /api/v1/verify/bulk/{jobId}

La risposta di base include job_id, name, status, total, processed, progress, summary, created_at e completed_at.

Quando sono disponibili risultati per un processo completato, parziale o non riuscito, la risposta include anche:

{
  "results": [
    {
      "email": "person@example.com",
      "status": "valid",
      "trust_score": 82,
      "checks": {},
      "provider": "example.com",
      "risk_factors": ["no_dmarc"]
    }
  ],
  "pagination": {"page": 1, "per_page": 100, "total": 1, "last_page": 1}
}

Parametri di query facoltativi:

Un processo annullato con righe elaborate può essere scaricato, ma usa l’endpoint di download per esportarlo.

Leggere gli stati senza supposizioni

Un client API deve eseguire il polling con attesa progressiva. Non inviare un nuovo processo collettivo solo perché quello esistente è ancora in attesa o una richiesta di rete è scaduta localmente.

Esempio di risposta dello stato

{
  "job_id": 42,
  "name": "September contacts",
  "status": "processing",
  "total": 1500,
  "processed": 400,
  "progress": 27,
  "summary": {"safe": 220, "valid": 105, "risky": 55, "invalid": 20},
  "created_at": "2026-09-04T13:15:00+00:00",
  "completed_at": null
}

summary può crescere durante il lavoro. Usa processed e total per visualizzare l’avanzamento, invece di sommare solo le categorie attualmente riconosciute dall’applicazione.

Scaricare un processo

GET /api/v1/verify/bulk/{jobId}/download

Il download è disponibile per processi completati, parziali o annullati con righe elaborate. Trasmette un CSV con le colonne Email, Status, Trust Score, Provider e Risk Factors.

Esempio:

curl -o september-results.csv \
  "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/download?filter=safe_risky" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Salva il file entro il periodo di conservazione dei risultati di 15 giorni. Il CSV è un’esportazione per il tuo flusso e non cambia consenso, iscrizioni o contatti in un altro sistema.

L’endpoint di download restituisce un conflitto finché non è disponibile un’esportazione elaborata. Controlla prima lo stato. Una richiesta riuscita trasmette il CSV senza wrapper JSON, quindi gestiscila come risposta file nel client HTTP.

Elencare i processi

GET /api/v1/verify/bulk

Usa page, per_page e facoltativamente status. per_page è 20 per impostazione predefinita e accetta da 1 a 100. Gli stati sono pending, processing, completed, partial, cancelled e failed.

La risposta contiene un array jobs e un oggetto pagination. Ogni record include ID, nome, stato, totale, quantità elaborata, avanzamento e timestamp.

Esempio:

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk?status=processing&per_page=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Usa l’endpoint elenco quando il worker si riavvia o devi riconciliare gli ID dei processi. Il nome non è un identificativo univoco; salva il job_id numerico restituito.

Struttura della risposta elenco

{
  "jobs": [
    {
      "job_id": 42,
      "name": "September contacts",
      "status": "completed",
      "total": 1500,
      "processed": 1500,
      "progress": 100,
      "created_at": "2026-09-04T13:15:00+00:00",
      "completed_at": "2026-09-04T13:28:00+00:00"
    }
  ],
  "pagination": {"page": 1, "per_page": 20, "total": 1, "last_page": 1}
}

Usa il parametro status quando una pagina operativa richiede solo processi attivi o conclusi. La paginazione è importante per gli account che verificano molte liste; non presumere che una risposta contenga l’intera cronologia.

Annullare un processo

POST /api/v1/verify/bulk/{jobId}/cancel

Annulla solo lavoro in attesa o in corso. Una risposta riuscita è:

{"status":"cancelled","credits_refunded":40}

Il rimborso copre il lavoro non elaborato. Se il processo raggiunge uno stato finale prima dell’annullamento, l’API restituisce un conflitto senza cambiare il risultato.

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/cancel \
  -H "Authorization: Bearer YOUR_API_TOKEN"

L’annullamento non elimina il processo. Scarica le righe elaborate se necessarie o elimina successivamente il record concluso.

Eliminare un processo

DELETE /api/v1/verify/bulk/{jobId}

Annulla prima un processo in corso. L’eliminazione rimuove definitivamente processo e risultati dopo che TrekMail elimina in sicurezza la lista sorgente preparata. Una risposta riuscita è:

{"deleted":true}

curl -X DELETE https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 843ef0c5-4dc0-4c09-bacd-5bd0fe87e847"

L’operazione è permanente per il record di verifica. Non ritira i CSV già scaricati dall’applicazione, quindi applica il tuo processo di conservazione a tali copie.

Ordine di eliminazione

1. Leggi lo stato del processo.
2. Annullalo se è in attesa o in elaborazione.
3. Salva le esportazioni elaborate da conservare.
4. Elimina il processo non in esecuzione con una chiave di idempotenza.
5. Rimuovi le copie detenute dal tuo sistema secondo le regole di privacy e conservazione.

Errori e nuovi tentativi

La verifica singola ha un limite di 60 richieste al minuto e l’invio collettivo di 10 richieste al minuto. Implementa nuovi tentativi con attesa progressiva, mantieni la stessa chiave per un nuovo tentativo collettivo e non riprovare alla cieca dopo un esito di rete ignoto.

Schema sicuro per riprovare

1. Genera e conserva una chiave di idempotenza prima dell’invio collettivo.
2. Invia la richiesta con quella chiave.
3. Se la risposta va persa, ripeti la richiesta identica con la stessa chiave.
4. Conserva il job_id restituito e smetti di creare nuovi invii per la lista sorgente.
5. Esegui il polling finché il processo raggiunge uno stato finale, poi scarica o elabora il risultato.

Per una verifica singola, un 503 temporaneo indica che il servizio non ha completato il controllo. Riprova più tardi con la normale attesa progressiva. Non trasformare tale risposta in un risultato Invalid nel tuo database.

Proteggere i dati dei contatti

Le liste email sono dati personali in molti contesti. Invia solo i dati necessari, limita l’accesso del token al sistema che esegue il processo ed evita di registrare array completi di indirizzi nei log. Se il logging serve, salva ID, quantità, tempi ed esito generale invece della lista completa.

TrekMail conserva i risultati per 15 giorni. Predisponi l’archiviazione sicura dell’esportazione o un percorso di eliminazione prima di integrare liste ad alto volume.

I segnali di verifica non dimostrano proprietà, consenso o consegna futura. Mantieni nell’applicazione la gestione delle autorizzazioni e delle soppressioni anche quando un indirizzo ottiene Safe.