Sviluppatori

Un'API di verifica email che funziona e basta

Verifica un indirizzo in tempo reale o invia un'intera lista come batch. Tutte le richieste usano HTTPS e restituiscono JSON. Crea le chiavi API nella dashboard, alla voce Chiavi API.

Ottieni una chiave API Leggi il riferimento

REST e JSON
Callback per i batch
Stessi crediti della dashboard

La pagina Chiavi API di BounceBell con le chiavi attive e un modulo per creare una nuova chiave

verify.sh

# Verify one addresscurl "https://bouncebell.com/api/v1/verify?email=rini.elizabeth@acme-foods.com" \  -H "Authorization: Bearer YOUR_API_KEY" { "status": "valid",  "reason": "mailbox_exists",  "did_you_mean": null }

Autenticazione

Invia la tua chiave API come bearer token nell'intestazione Authorization di ogni richiesta. Conserva le chiavi sul tuo server. Non inserirle mai nel codice del browser o nelle app mobili.

Authorization: Bearer YOUR_API_KEY

L'URL di base di ogni endpoint è https://bouncebell.com/api/v1.

Verifica un indirizzo

GET https://bouncebell.com/api/v1/verify

Parametro	Obbligatorio	Descrizione
`email`	Sì	L'indirizzo da verificare. Codificalo per l'URL.
`timeout`	No	Secondi di attesa per il server di posta, da 3 a 30. Predefinito 10. Se il tempo scade, lo stato è `unknown` e non viene usato alcun credito.

Esempio

curl "https://bouncebell.com/api/v1/verify?email=rini.elizabeth%40acme-foods.example" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "email": "rini.elizabeth@acme-foods.example",
  "status": "valid",
  "reason": "mailbox_exists",
  "domain": "acme-foods.example",
  "mx_record": "mx1.acme-foods.example",
  "disposable": false,
  "role": false,
  "free_provider": false,
  "catch_all": false,
  "did_you_mean": null,
  "checked_at": "2026-10-30T09:30:12Z",
  "credits_used": 1
}

Campi del risultato

Campo	Tipo	Descrizione
`email`	string	L'indirizzo come lo hai inviato.
`status`	string	L'esito. Vedi gli stati.
`reason`	string	Il motivo dell'esito, ad esempio `mailbox_not_found` o `no_mail_server`.
`domain`	string	La parte del dominio, in minuscolo.
`mx_record`	string or null	Il server di posta con la priorità più alta.
`disposable`	boolean	Vale true se il dominio è un servizio di caselle temporanee.
`role`	boolean	Vale true per le caselle condivise come info@ o support@.
`free_provider`	boolean	Vale true per i provider di posta gratuiti come Gmail.
`catch_all`	boolean	Vale true quando il dominio accetta qualsiasi indirizzo.
`did_you_mean`	string or null	Un indirizzo corretto quando il dominio sembra contenere un errore di battitura.
`checked_at`	string	Quando è stata eseguita la verifica, in formato ISO 8601 UTC.
`credits_used`	integer	1, oppure 0 quando lo stato è `unknown`.

Stati

Stato	Significato	Azione suggerita
`valid`	La casella esiste e accetta posta.	Invia
`invalid`	L'indirizzo, il dominio o la casella non esiste.	Rimuovi
`disposable`	Un servizio di caselle di posta temporanee.	Rimuovi
`catch_all`	Il dominio accetta tutti gli indirizzi, quindi la casella non può essere confermata.	Da controllare
`role`	Una casella condivisa che esiste.	Da controllare
`unknown`	Il server di posta non ha dato una risposta in tempo. Non addebitato.	Riprova più tardi

Batch

Invia fino a 100.000 indirizzi in una sola richiesta. Il batch viene eseguito in background: interroga il suo stato oppure indica una callback_url che chiameremo al termine del batch.

Crea un batch

POST https://bouncebell.com/api/v1/batches

curl -X POST "https://bouncebell.com/api/v1/batches" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "October import", "emails": ["a@example.com", "b@example.com"],
       "callback_url": "https://yourapp.example/hooks/bouncebell"}'

{ "id": "bat_8f2k1q3m9x7w4p", "status": "queued", "total": 2, "done": 0 }

I crediti per ogni indirizzo unico vengono bloccati alla creazione del batch, e i risultati sconosciuti vengono rimborsati al termine. Il callback riceve una POST con {"event": "batch.completed", "batch_id": "...", "status": "done", "counts": {...}}. Gli URL di callback devono usare HTTPS.

Controlla l'avanzamento

GET https://bouncebell.com/api/v1/batches/{id}

{ "id": "bat_8f2k1q3m9x7w4p", "status": "running", "total": 2, "done": 1 }

Lo stato è queued, running o done. Quando è done, la risposta contiene anche i counts per stato.

Scarica i risultati

GET https://bouncebell.com/api/v1/batches/{id}/results

Restituisce JSON per impostazione predefinita. Aggiungi ?format=csv per ottenere un file CSV. Ogni riga ha gli stessi campi di una verifica singola.

Crediti

GET https://bouncebell.com/api/v1/credits

{ "credits_remaining": 33420 }

Errori e limiti

Gli errori restituiscono un corpo JSON con un codice error e un message leggibile.

Codice HTTP	Errore	Cosa fare
400	`bad_request`	Un parametro manca o non è corretto. Leggi il messaggio.
401	`invalid_key`	Controlla che la chiave sia corretta e non sia stata revocata.
402	`no_credits`	Acquista altri crediti.
403	`email_not_confirmed`	Apri il link di conferma che ti abbiamo inviato via email al momento della registrazione.
404	`not_found`	Il batch non esiste o è stato eliminato dopo 30 giorni.
429	`rate_limited`	Rallenta. Attendi i secondi indicati nell'intestazione `Retry-After`.
500	`server_error`	Riprova dopo una breve attesa. Se il problema persiste, contatta il supporto.

Le verifiche singole sono limitate a 20 richieste al secondo per chiave. Contattaci se te ne servono di più.