Guida rapida all’API di TrekMail Email Verifier

Utilizza l’API quando la verifica deve far parte del tuo prodotto o flusso di importazione. Crea un token con verify:read e verify:write, mantienilo segreto e chiama lo stesso host che usi per accedere. Negli esempi, sostituisci https://YOUR-TREKMAIL-HOST e YOUR_API_TOKEN.

1. Creare un token

1. Apri Dashboard → AI Agents & API.
2. Crea un token.
3. Abilita verify:read e verify:write.
4. Conserva il token in modo sicuro. Viene mostrato una sola volta.

Invialo con ogni richiesta:

Authorization: Bearer YOUR_API_TOKEN

Conserva il token in un archivio dei segreti o in una variabile di ambiente. Non inserirlo nel codice del browser, in un repository pubblico, in una richiesta di assistenza o in un file di contatti esportato. Se sospetti che sia stato esposto, revocalo e creane un altro nel dashboard.

2. Verificare un indirizzo

Utilizza POST /api/v1/verify per ottenere immediatamente il risultato di un singolo indirizzo. Quick è l’impostazione predefinita quando mode viene omesso.

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"}'

La risposta contiene campi di primo livello stabili, come indirizzo, stato, punteggio di affidabilità, provider, fattori di rischio e crediti rimanenti. L’oggetto checks registra i riscontri dettagliati e può variare quando un controllo non è disponibile o la modalità Deep offre informazioni aggiuntive.

{
  "email": "person@example.com",
  "status": "valid",
  "trust_score": 82,
  "provider": "example.com",
  "risk_factors": ["no_dmarc"],
  "checks": {
    "syntax": {"pass": true, "score_impact": 0},
    "dmarc_record": {"pass": false, "score_impact": -10}
  },
  "credits_remaining": {
    "monthly": 99,
    "purchased": 0
  }
}

Leggi prima status e trust_score. Considera le singole chiavi dei controlli come dettagli di supporto, non come garanzia di proprietà della casella o di consegna.

L’endpoint singolo ha un limite di 60 richieste al minuto per la route. Se controlli un indirizzo inserito durante la registrazione, chiamalo dopo una convalida di base lato client e mostra un errore semplice quando il servizio non è temporaneamente disponibile, invece di bloccare la persona a tempo indefinito.

3. Inviare un processo in blocco

Le richieste in blocco accettano un array JSON emails, non il caricamento di un file. Includi una chiave di idempotenza affinché un nuovo tentativo di rete non crei un secondo processo.

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

L’elenco può contenere fino a 50,000 voci. TrekMail normalizza i duplicati ed esclude dal processo le voci con sintassi non valida. La risposta indica l’ID del processo, il numero accettato, un piccolo campione rifiutato, i crediti addebitati e la ripartizione del prezzo Deep.

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

probe è il numero addebitato alla tariffa Deep completa. skip è il numero addebitato alla tariffa normale perché il provider non offre riscontri utili a livello di casella. La risposta fornisce il costo definitivo per quell’invio.

Prima di inviare un elenco completo, rimuovi nel tuo strumento di importazione i valori che non sono indirizzi. L’API elimina i duplicati e indica il numero rifiutato, ma la convalida alla fonte crea una traccia di audit più chiara. Se la richiesta scade dal punto di vista dell’applicazione, ripeti la stessa richiesta in blocco con la stessa chiave di idempotenza e controlla l’ID restituito prima di creare un altro invio.

4. Controllare e scaricare

Controlla il processo con GET /api/v1/verify/bulk/{jobId} finché non raggiunge uno stato finale:

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

La risposta include status, total, processed, progress, summary, ora di creazione e ora di completamento. I processi completati e parziali includono un array results impaginato.

Esegui il controllo a intervalli ragionevoli con attesa progressiva. Un processo può restare in attesa prima dell’inizio e Deep può richiedere più tempo quando un provider ricevente offre riscontri aggiuntivi. Non presumere un tempo di completamento fisso dalla sola dimensione dell’elenco.

Puoi richiedere una pagina dei risultati più piccola o cercare un indirizzo noto quando i risultati sono disponibili:

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42?per_page=50&search=%40example.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Scarica un processo elaborato come CSV:

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

I filtri di esportazione dell’API sono all, safe e safe_risky (Safe + Valid + Risky).

Per interrompere un processo in attesa o in esecuzione, usa l’endpoint di annullamento. Rimborsa il lavoro non elaborato e conserva le righe elaborate:

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

Elimina un processo solo quando vuoi rimuovere sia il record del verificatore sia i risultati. Se è ancora in esecuzione, annullalo prima e usa quindi l’endpoint di eliminazione con una chiave di idempotenza. Il riferimento completo mostra entrambe le chiamate.

5. Gestire le risposte comuni

• 402: l’account necessita di altri crediti.
• 422: controlla il corpo della richiesta, la modalità selezionata o la chiave di idempotenza obbligatoria per una richiesta in blocco.
• 429: riduci la frequenza e riprova con attesa progressiva.
• 503: la verifica non è temporaneamente disponibile. Riprova in seguito; una verifica singola non riuscita viene rimborsata.

Elenco di controllo per un’integrazione in produzione

1. Conserva il token sul server e assegna solo i due ambiti necessari del verificatore.
2. Convalida e normalizza i contatti prima di chiamare l’API in blocco.
3. Salva l’ID del processo, l’identificatore dell’elenco inviato, la chiave di idempotenza e il valore credits_charged restituito.
4. Controlla con attesa progressiva invece di usare un ciclo continuo.
5. Salva o elabora il CSV prima della fine del periodo di conservazione di 15 giorni.
6. Mantieni le decisioni relative a consenso, annullamento dell’iscrizione e soppressione nella tua applicazione. Un risultato del verificatore non le sostituisce.

Utilizza il Riferimento API REST di Email Verifier per tutti gli endpoint, gli ambiti e i campi di risposta.