Documentazione

Gli endpoint che usi davvero.

Una chiave, due endpoint: verificare un indirizzo o verificare una lista.

01Autenticazione

Una chiave, inviata come bearer token.

Ogni richiesta porta la tua chiave API. Le chiavi si creano dalla dashboard e hanno gli scope verify e bulk.

Authorization: Bearer bi_live_…
Content-Type: application/json

Una chiave viene mostrata solo alla creazione; conserviamo solo il prefisso. Se trapela, revocala e creane un'altra; le altre continuano a funzionare.

02Singolo / tempo reale

Verificare un indirizzo.

Verifica sincrona: sintassi, DNS, MX e una conversazione SMTP con il server destinatario. Un credito.

POSThttps://api.bounceintel.com/v1/check_email

Verificare un indirizzo

Restituisce il report completo con punteggio. Latenza mediana sotto i 500 ms; prevedi 30 s con server lenti.

verify.sh
curl -sS -X POST 'https://api.bounceintel.com/v1/check_email' \
  -H "Authorization: Bearer $BOUNCEINTEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]"
}'
Risposta200
{
  "input": "[email protected]",
  "is_reachable": "safe",
  "provider": "google_workspace",
  "provider_confidence": "high",
  "score": {
    "score": 100,
    "category": "valid",
    "sub_reason": "deliverable",
    "safe_to_send": true,
    "confidence": 95,
    "confidence_level": "high",
    "reason_codes": ["provider_reputation"],
    "signals": {
      "valid_syntax": true,
      "has_mx_records": true,
      "smtp_can_connect": true,
      "smtp_is_deliverable": true,
      "smtp_is_catch_all": false
    }
  },
  "syntax": { "username": "ada", "domain": "stripe.com", "is_valid_syntax": true },
  "mx": { "accepts_mail": true, "records": ["aspmx.l.google.com."] },
  "smtp": {
    "can_connect_smtp": true,
    "is_deliverable": true,
    "is_catch_all": false,
    "has_full_inbox": false,
    "is_disabled": false
  },
  "misc": { "is_disposable": false, "is_role_account": false, "is_b2c": false },
  "bounce_risk": { "score": 8, "category": "low", "action": "send", "confidence": 0.71 }
}
mx, smtp e misc sono union: o l'oggetto di dettaglio, o un oggetto di errore se la fase non è riuscita. Verifica il tipo prima di leggere.

03In blocco / asincrono

Verificare una lista.

Invia l'intera lista in una richiesta, monitora l'avanzamento e pagina i risultati. Un credito per indirizzo, addebitato all'invio.

POSThttps://api.bounceintel.com/v1/bulk

Inviare una lista

Invia tutti gli indirizzi in una chiamata. La risposta è un id di job; la verifica prosegue in background.

bulk.sh
curl -sS -X POST 'https://api.bounceintel.com/v1/bulk' \
  -H "Authorization: Bearer $BOUNCEINTEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
}'
Risposta200
{
  "job_id": 8
}
I crediti sono addebitati per l'intero lotto all'invio, in modo atomico: due job simultanei non possono spendere lo stesso saldo. Se il lotto supera i crediti disponibili l'intera richiesta è rifiutata; nulla viene addebitato parzialmente.
GEThttps://api.bounceintel.com/v1/bulk/{job_id}

Verificare l'avanzamento

Interroga mentre il job gira. finished_at resta null finché tutti gli indirizzi non sono stati elaborati.

status.sh
curl -sS -X GET 'https://api.bounceintel.com/v1/bulk/{job_id}' \
  -H "Authorization: Bearer $BOUNCEINTEL_KEY" \
  -H "Accept: application/json"
Risposta200
{
  "job_id": 8,
  "created_at": "2026-09-02T15:16:15.447365Z",
  "finished_at": null,
  "total_records": 4,
  "total_processed": 2,
  "summary": {
    "total_safe": 1,
    "total_risky": 0,
    "total_invalid": 1,
    "total_unknown": 0
  },
  "job_status": "Running"
}
Interroga ogni pochi secondi, non in un ciclo stretto. I totali del riepilogo si aggiornano in tempo reale.
GEThttps://api.bounceintel.com/v1/bulk/{job_id}/results?format=json&limit=1000&offset=0

Recuperare i risultati

Pagina i risultati completati. Ogni riga ha la stessa forma di una verifica singola.

results.sh
curl -sS -X GET 'https://api.bounceintel.com/v1/bulk/{job_id}/results?format=json&limit=1000&offset=0' \
  -H "Authorization: Bearer $BOUNCEINTEL_KEY" \
  -H "Accept: application/json"
Risposta200
{
  "results": [
    {
      "input": "[email protected]",
      "is_reachable": "safe",
      "provider": "google_workspace",
      "score": {
        "score": 100,
        "category": "valid",
        "safe_to_send": true,
        "sub_reason": "deliverable",
        "reason_codes": ["provider_reputation"]
      },
      "syntax": { "username": "ada", "domain": "stripe.com", "is_valid_syntax": true },
      "mx": { "accepts_mail": true, "records": ["aspmx.l.google.com."] },
      "smtp": { "can_connect_smtp": true, "is_deliverable": true, "is_catch_all": false },
      "misc": { "is_disposable": false, "is_role_account": false },
      "bounce_risk": { "score": 8, "category": "low", "action": "send" }
    }
  ]
}
limit vale 50 per JSON. Indicalo esplicitamente, fino a 1000, e pagina con offset. Usa format=csv per scaricare tutto come file.

04Assistenti IA

Verifica dal tuo assistente IA.

BounceIntel mette a disposizione un server MCP all'indirizzo https://api.bounceintel.com/mcp. Collega Claude Code, Cursor, VS Code o qualsiasi client che supporti MCP via HTTP: l'assistente verificherà indirizzi e liste per te, con la stessa chiave API e gli stessi crediti.

terminal
claude mcp add --transport http bounceintel https://api.bounceintel.com/mcp \
  --header "Authorization: Bearer $BOUNCEINTEL_KEY"

Invia la chiave API come bearer token, esattamente come per l'API REST. Gli esempi la leggono da BOUNCEINTEL_KEY, così la chiave non finisce in file che potresti caricare nel repository.

StrumentoScope della chiaveCosa fa
verify_emailverifyVerifica un indirizzo e restituisce verdetto, punteggio e motivo. Un credito.
verify_email_listbulkAvvia un job in blocco per una lista e ne restituisce l'id. Un credito per indirizzo unico.
get_bulk_jobbulkMostra l'avanzamento di un job e quanti indirizzi hanno ciascun verdetto. Nessun credito.
get_bulk_resultsbulkRestituisce i verdetti di un job completato, una pagina alla volta, filtrati per verdetto se serve. Nessun credito.
get_accountqualsiasi chiaveMostra il piano, i crediti rimasti e quando si rinnovano. Nessun credito.

I job in blocco girano in background: l'assistente avvia il job, ne controlla l'avanzamento e poi legge i risultati. Gli strumenti che una chiave non può usare restano nascosti all'assistente.

05Errori

Cosa può tornare.

Ogni errore restituisce un JSON con un campo error. Questi sono quelli da gestire.

StatoErroreCosa fare
400invalid_requestCorpo malformato o indirizzo inutilizzabile. Correggi e reinvia.
401unauthorizedChiave assente, errata o revocata.
403forbiddenChiave valida ma priva dello scope richiesto.
429rate_limitedTroppe richieste. Attendi e riprova.
429quota_exceededCrediti esauriti. Solo l'acquisto risolve; riprovare non serve.
503unavailableNon è stato possibile stabilire la tua quota. Transitorio: riprova a breve.

06Playground

Provalo con la tua chiave.

Esegue una verifica reale sul tuo account. Una verifica singola consuma un credito; il bulk uno per indirizzo, addebitato all'invio.

Incolla la tua chiave API per provare. La chiave viene inviata al nostro backend, usata una volta e non conservata. I controlli come ospite non usano la tua chiave.

URL di base: https://api.bounceintel.com

POST https://api.bounceintel.com/v1/check_email

verify.sh
curl -sS -X POST 'https://api.bounceintel.com/v1/check_email' \
  -H "Authorization: Bearer $BOUNCEINTEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]"
}'

Gli snippet copiati usano $BOUNCEINTEL_KEY, mai la chiave che hai inserito.