PER SVILUPPATORI

API di verifica email.

Usa la verifica di un singolo indirizzo per i moduli o le attività asincrone per le liste dei clienti. Mantieni il tuo attuale provider email.

INIZIA CON UN INDIRIZZO

La tua prima richiesta.

Usa l’endpoint demo gratuito senza chiave. Ha limiti di frequenza ed è pensato per provare il servizio.

curl -X POST https://api.zbounce.net/v1/demo \
  -H 'Content-Type: application/json' \
  -d '{"email":"hello@example.com"}'

Per le verifiche a pagamento, acquista un pacchetto e usa /v1/fast-verify con la tua chiave in X-API-Key. Non inserire le chiavi in URL, sistemi di controllo versione o strumenti di analisi.

curl -X POST https://api.zbounce.net/v1/fast-verify \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $ZBOUNCE_API_KEY" \
  -d '{"email":"hello@example.com"}'

Esempio in Python

import os, requests

response = requests.post(
    "https://api.zbounce.net/v1/fast-verify",
    headers={"X-API-Key": os.environ["ZBOUNCE_API_KEY"]},
    json={"email": "hello@example.com"},
    timeout=35,
)
response.raise_for_status()
print(response.json())

Esempio in Node.js

const response = await fetch("https://api.zbounce.net/v1/fast-verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.ZBOUNCE_API_KEY,
  },
  body: JSON.stringify({ email: "hello@example.com" }),
  signal: AbortSignal.timeout(35000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

UNA LISTA IN INGRESSO, RISULTATI IN USCITA

Verifica una lista più grande.

POST /v1/tasks

Invia fino a 10.000 indirizzi per attività. Conserva l’ID attività restituito e controlla accepted, skipped e invalids: non tutti gli input vengono necessariamente messi in coda. Gli indirizzi duplicati, malformati ed esclusi possono essere rimossi, e un saldo basso può causare un’accettazione parziale.

curl -X POST https://api.zbounce.net/v1/tasks \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $ZBOUNCE_API_KEY" \
  -d '{"emails":["hello@example.com","contact@example.org"]}'

Controlla lo stato periodicamente, poi recupera ogni pagina di risultati. Una risposta che contiene solo input non validi può avere un ID attività vuoto; non interrogarlo.

curl "https://api.zbounce.net/v1/tasks/$TASK_ID" \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

curl "https://api.zbounce.net/v1/tasks-results/$TASK_ID?page=1&per_page=100" \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

I risultati delle attività completate sono in JSON. Continua a recuperare le pagine finché non hai ottenuto l’intera lista accettata. Per ricevere automaticamente il completamento, passa un webhook con mode: "completed" quando crei l’attività.

{
  "emails": ["hello@example.com"],
  "webhook": {
    "url": "https://your-app.example/hooks/verification",
    "mode": "completed",
    "secret": "YOUR_PRIVATE_WEBHOOK_SECRET"
  }
}

Consulta lo schema per la configurazione del webhook e la verifica della firma prima di attivarlo in produzione.

CAPIRE LA RISPOSTA

Formato valido non significa esistenza.

Sono segnali distinti. Un indirizzo ben formato può comunque essere inesistente, usa e getta o impossibile da confermare.

Campo	Significato
`valid`	L’indirizzo ha superato la validazione della sintassi. Questo da solo non conferma la casella.
`exists`	Il risultato del controllo della casella. Interpretalo insieme agli errori e ai segnali catch-all.
`disposable`	Il dominio è stato riconosciuto come provider di email temporanee.
`accept_all`	Il server accetta indirizzi arbitrari; la casella specifica non può essere confermata in modo affidabile.
`error_category`	Spiega un errore o un rischio, ad esempio no_mx, risky o un problema temporaneo del server.
`permanent_error`	Durante la verifica è stato restituito un errore permanente. Un errore temporaneo non va considerato un rifiuto permanente.
`ttl`	Un’indicazione in secondi per i nuovi tentativi o la cache, quando restituita.

La verifica non può garantire la consegna, eliminare i reclami né dimostrare la titolarità di una casella.

Conosci il tuo saldo.

GET /v1/me

curl https://api.zbounce.net/v1/me \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

La risposta include i crediti rimanenti, riservati e utilizzati, il tipo di chiave e la scadenza. Una verifica standard usa un credito; il filtraggio e l’addebito effettivi dipendono dall’endpoint e dall’accettazione dell’attività. Controlla la risposta prima di considerare elaborata un’intera lista caricata.

Una risposta 429 indica che le richieste vengono limitate. Attendi prima di riprovare. Nell’attuale API altri errori possono essere restituiti come JSON o testo; non interpretare gli errori HTTP come risultati di verifica.

Il contratto di verifica.

Scarica il JSON OpenAPI

Il contratto pubblico copre demo, verifica rapida, attività, stato delle attività, risultati e saldo dell’account. Gli endpoint di invio e di amministrazione non rientrano in questo riferimento per la verifica.

Ti serve aiuto per collegare la tua piattaforma? support@zbounce.net