API

Un'API REST su HTTPS. Tutto è JSON, ogni campo è snake_case e la base è https://listcheckup.com. Non c'è nessun SDK da installare e niente da aspettare — crea una chiave e i due comandi qui sotto funzionano.

Autenticazione

Ogni richiesta porta con sé una chiave API, creata nella tua dashboard. Le chiavi iniziano con lck_live_, possono avere una scadenza e possono essere revocate in qualsiasi momento.

curl "https://listcheckup.com/v1/me" \
  -H "Authorization: Bearer lck_live_..."

GET /v1/me risponde con l'account a cui appartiene la chiave e il suo saldo: è il modo più rapido per confermare che una chiave funziona:

{ "email": "[email protected]", "credits": 24600 }

Senza chiave, o con una chiave revocata o scaduta, ogni endpoint risponde 401 e dice di quale caso si tratta — una chiave revocata e un refuso richiedono rimedi diversi.

Rate limit

120 richieste per iniziare, che si ricaricano al ritmo di 60 al minuto, per chiave. È un tetto sul volume delle richieste, non sugli indirizzi: una lista da mezzo milione di indirizzi è una sola richiesta. Superarlo restituisce 429, e il rimedio è aspettare.

Verificare un indirizzo

Il verdetto arriva direttamente nella risposta. Usalo quando qualcuno sta aspettando — un modulo di iscrizione, un checkout — non per una lista che hai già.

curl "https://listcheckup.com/v1/[email protected]" \
  -H "Authorization: Bearer lck_live_..."

Esiste anche POST /v1/verify con { "email": "..." } nel body, se una query string è scomoda. Entrambi restituiscono la stessa cosa:

{
  "email": "[email protected]",
  "normalized_email": "[email protected]",
  "local_part": "someone",
  "domain": "example.com",
  "status": "valid",
  "reason": "mailbox_accepted",
  "confidence": 95,
  "duration_ms": 412
}

status è uno di cinque valori, e confidence va da 0 a 100 e indica quanto ci si può fidare di quello status. Un catch-all ottiene un punteggio basso anche se il server ha accettato l'indirizzo, perché lì l'accettazione non prova nulla.

status	Cosa significa
valid	La casella esiste e può ricevere posta.
invalid	Non può ricevere posta. Rimuovilo.
risky	Funziona, ma è un indirizzo usa e getta o una casella condivisa, non una persona.
catch_all	Il dominio accetta qualsiasi indirizzo, quindi nessuno può dire se questo esista davvero.
unknown	Il server di posta non ha voluto rispondere. Un fatto che riguarda la loro policy, non l'indirizzo.

Paghi solo quando c'è una risposta. catch_all e unknown non costano nulla, perché il lavoro è stato fatto ma il server di posta si è rifiutato di dirlo — fartelo pagare significherebbe farti pagare la nostra impossibilità di scoprirlo.

Verificare una lista

Quattro chiamate: crea, avvia, controlla, raccogli.

1. Creare

Gli indirizzi come JSON, non come upload di file — li hai già in mano come stringhe, e costruire un body multipart per inviare stringhe è lavoro sprecato.

curl -X POST "https://listcheckup.com/v1/lists" \
  -H "Authorization: Bearer lck_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "march-subscribers", "emails": ["[email protected]", "[email protected]"]}'

Non viene ancora addebitato nulla. La risposta è il riepilogo della lista con il prezzo, così puoi decidere prima di spendere qualcosa:

{
  "id": "7f3c1d20-9a4b-4c8e-8f21-5b6d7e8a9c04",
  "name": "march-subscribers",
  "status": "awaiting_confirmation",
  "addresses": 24600,
  "duplicates": 1020,
  "not_addresses": 180,
  "unique": 23580,
  "excluded": 0,
  "price": 23400,
  "checked": 0,
  "credits_charged": 0,
  "failure_reason": null,
  "created_at": "2026-03-18T09:12:00+00:00",
  "completed_at": null
}

price è in crediti ed è quanto costerà avviarla. I duplicati sono contati una sola volta e le righe che non sono indirizzi non vengono mai addebitate: ecco perché è più basso di addresses.

2. Avviare

curl -X POST "https://listcheckup.com/v1/lists/<id>/start" \
  -H "Authorization: Bearer lck_live_..."

Questa è la chiamata che spende i crediti. 402 significa che il saldo non basta, e non è stato addebitato né avviato nulla.

3. Sapere quando ha finito

Registra un webhook e inviamo una POST al tuo server nel momento in cui una lista finisce — firmata, ritentata se il tuo lato è giù. È questo il modo giusto di farlo.

Se preferisci chiedere tu, GET /v1/lists/<id> restituisce lo stesso riepilogo di sopra, con status e checked che avanzano. Interrogalo con parsimonia; un webhook non ti costa nessuna richiesta.

status	Significato
uploaded	Accettata, non ancora letta.
reading	In conteggio. price è null finché questa fase non finisce.
awaiting_confirmation	Contata e prezzata. Non viene addebitato nulla finché non la avvii.
queued	Avviata, in attesa di un worker.
running	In corso. checked sale.
completed	Finita. I risultati sono pronti.
failed	Interrotta. Vedi failure_reason.
cancelled	Interrotta da te. I crediti non usati vengono restituiti.

4. Raccogliere i risultati

curl "https://listcheckup.com/v1/lists/<id>/results?limit=500&skip=0" \
  -H "Authorization: Bearer lck_live_..."

limit è 500 per impostazione predefinita, con un massimo di 2.000; sfoglia le pagine con skip. Aggiungi include=valid,risky per restringere alle categorie che ti interessano.

{
  "id": "7f3c1d20-...",
  "status": "completed",
  "total": 24600,
  "offset": 0,
  "returned": 500,
  "results": [
    {
      "row": 1,
      "email": "[email protected]",
      "status": "valid",
      "confidence": 95,
      "reason": "mailbox_accepted",
      "billable": true,
      "duplicate_of_row": null
    }
  ]
}

row è la posizione nella lista che hai inviato, così i risultati si allineano con i tuoi dati senza dover incrociare gli indirizzi.

Eliminare

DELETE /v1/lists/<id> elimina una lista e i suoi risultati. Tutto ciò che non è stato speso su una lista mai avviata torna indietro.

Webhook

Aggiungi un endpoint nella dashboard e inviamo una POST firmata quando una lista finisce:

{
  "event": "list.finished",
  "occurred_at": "2026-03-18T09:41:00+00:00",
  "list": {
    "id": "7f3c1d20-...",
    "name": "march-subscribers",
    "checked": 24600,
    "safe_to_send": 12000,
    "to_remove": 7400,
    "uncertain": 3100
  }
}

Rispondi con un qualsiasi 2xx. Con qualsiasi altra risposta riproviamo, sei volte nell'arco di circa un giorno. Ogni richiesta porta una firma HMAC-SHA256 che verifichi con il tuo signing secret; lo schema esatto, con un esempio svolto, è mostrato accanto al secret quando crei l'endpoint.

Slack funziona senza nulla di tutto questo. Incolla l'URL di un incoming webhook Slack al posto del tuo, e inviamo un messaggio che Slack sa mostrare invece del JSON qui sopra — niente da scrivere, niente da ospitare. I tentativi ripetuti e il registro delle consegne funzionano allo stesso modo.

Usarla da un assistente AI

C'è un server MCP su https://listcheckup.com/mcp. Punta un assistente che supporta MCP — Claude, o un editor come Cursor — a quell'URL con la stessa chiave API, e potrà verificare indirizzi per te senza che nessuno scriva codice.

Collegarlo

In qualunque modo ti colleghi, la chiave viaggia sempre allo stesso modo: un header Authorization: Bearer <key>. Cambia solo dove la scrivi.

Claude Code — un solo comando:

claude mcp add --transport http listcheckup https://listcheckup.com/mcp \
  --header "Authorization: Bearer lck_live_..."

Claude Desktop, Cursor e la maggior parte degli altri client — nel file di configurazione:

{
  "mcpServers": {
    "listcheckup": {
      "url": "https://listcheckup.com/mcp",
      "headers": { "Authorization": "Bearer lck_live_..." }
    }
  }
}

Verificare che funzioni

Prima di collegarlo a qualcosa, chiedi al server cosa sa fare:

curl -X POST "https://listcheckup.com/mcp"   -H "Authorization: Bearer lck_live_..."   -H "Content-Type: application/json"   -H "Accept: application/json, text/event-stream"   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Sei strumenti elencati significa che sei connesso. "error": "unauthorized" significa che la chiave non è arrivata — quasi sempre manca la parola Bearer con il suo spazio, oppure la chiave è stata troncata incollandola. Una chiave è lunga una cinquantina di caratteri e inizia con lck_live_.

Cosa sa fare

Strumento	Cosa fa
check_email	Un indirizzo. Costa un credito, a meno che la risposta sia catch-all o unknown.
get_balance	Crediti rimasti. Gratis.
create_list	Invia una lista e ottieni un prezzo. Non addebita nulla.
start_list	Avvia la verifica. Questa è la chiamata che spende i crediti.
get_list	Stato e avanzamento. Gratis.
get_list_summary	I conteggi una volta finita. Gratis.

Prezzo e avvio sono due strumenti separati, di proposito: così un assistente deve mostrarti quanto costerà una lista prima che venga speso qualcosa, e tu puoi dire di no. Nessuno strumento accetta un account come argomento — è la chiave nell'header a decidere di chi sono i crediti usati, quindi niente di ciò che un assistente legge o si sente dire può indirizzarlo verso l'account di qualcun altro.

Tratta la chiave come una password

Qualsiasi cosa la possieda può spendere i tuoi crediti. Sta in un file di configurazione in chiaro, quindi tieni quel file fuori da repository condivisi, e revoca la chiave se finisce dove non doveva — la revoca ha effetto immediato, per l'API come per questo server. Dai a ogni macchina la sua chiave e potrai revocarne una senza disturbare le altre.

Errori

Ogni errore è JSON, con un codice stabile e una frase pensata per un essere umano:

{ "error": "unauthorized", "message": "Provide your API key as 'Authorization: Bearer <key>'." }

Codice	Significato
400	Qualcosa nella richiesta manca o è sbagliato. Il body dice cosa.
401	Nessuna chiave, o una chiave sconosciuta, revocata o scaduta.
402	Crediti insufficienti. Non è stato addebitato né avviato nulla.
404	Nessuna lista del genere su questo account.
409	La lista non è in uno stato in cui l'operazione ha senso — già avviata, per esempio.
429	Rate limit superato. Aspetta.

Cosa non farà

L'API verifica indirizzi che possiedi già. Non trova, non genera e non fornisce indirizzi, e non invia mai posta agli indirizzi che verifica — la conversazione con ciascun server di posta si chiude prima che un messaggio esista. Usarla su liste raccolte con scraping, comprate o noleggiate è vietato; vedi l'uso accettabile.