Lingua

English Italiano Deutsch Español Português (Brasil)Français

Cerchi una panoramica? Leggi la pagina sull'API di verifica email o sull'API di validazione email per i moduli di iscrizione.

Documentazione API di verifica email

Verifica email singole, avvia batch in blocco e controlla a fondo gli indirizzi catch-all e protetti da SEG. Tutti gli endpoint usano JSON, si autenticano con una chiave API e ti addebitano solo le verifiche riuscite.

Introduzione

L'API di Giggal.ai ti permette di verificare singoli indirizzi email, avviare batch fino a 50.000 email per job e controllare a fondo gli indirizzi catch-all e protetti da SEG, con una semplice REST API in JSON. Ogni verifica riuscita usa crediti del tuo account.

URL di base

https://api.giggal.ai/v1

Ottieni una chiave API

Crea una chiave API dalla dashboard di Giggal.ai: apri la scheda Developer API nella barra laterale e clicca Create API Key. Ogni chiave è legata al tuo account, registra il proprio utilizzo e puoi revocarla in qualsiasi momento.

Apri la scheda Developer API

Struttura della risposta

Ogni risposta segue la stessa struttura JSON:

// Success
{ "success": true, "data": { ... }, "meta": { ... } }

// Error
{ "success": false, "error": "Human-readable error message" }

Avvio rapido: verifica una email con cURL

curl -X POST https://api.giggal.ai/v1/verify \
  -H "Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"email":"info@giggal.ai"}'

Autenticazione

Invia la tua chiave API con ogni richiesta, in uno di questi due header. Funzionano entrambi.

Opzione 1: token Bearer

Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx

Opzione 2: header X-API-Key

X-API-Key: tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx

Una chiave mancante, non valida o revocata restituisce HTTP 401. Non mettere mai le chiavi API nel codice lato client. Fai passare le chiamate dal tuo backend.

Idempotenza (verifica in blocco e catch-all)

Per POST /v1/verify-batch e POST /v1/catchall, invia un header Idempotency-Key. I nuovi tentativi con la stessa chiave restituiscono la risposta originale, senza creare un job doppio e senza addebitare due volte i crediti.

Idempotency-Key: 2026-07-24-list-batch-42

Verifica singola

1 endpoint in questo gruppo.

POST/v1/verify

Verifica una singola email

Verifica un indirizzo email in modo sincrono. Costa 1 credito. Se il dominio è catch-all, la verifica approfondita parte subito e la risposta include catch_all_score e catch_all_verdict.

Autorizzazioni

api_key_auth

Corpo della richiesta

Obbligatorio

string

L'indirizzo email da verificare.

POST/v1/verify

Esempi di risposta

{
  "success": true,
  "data": {
    "email": "info@giggal.ai",
    "is_valid": true,
    "status": "deliverable",
    "risk_level": "low",
    "deliverability_score": 89,
    "details": {
      "general": {
        "domain": "giggal.ai",
        "reason": "Mailbox confirmed deliverable"
      },
      "attributes": {
        "free_email": false,
        "role_account": false,
        "disposable": false,
        "catch_all": true,
        "has_plus_tag": false,
        "mailbox_full": false,
        "no_reply": false
      },
      "mail_server": {
        "smtp_provider": "google",
        "mx_record": "aspmx.l.google.com",
        "implicit_mx": null
      },
      "blacklist": {
        "is_blacklisted": false,
        "blacklists_found": [],
        "blacklist_reasons": [],
        "reputation_score": 100,
        "last_checked": "2026-07-23T20:47:15.540Z"
      },
      "sub_status": null
    },
    "catch_all_score": 89,
    "catch_all_verdict": "valid"
  },
  "meta": {
    "creditsUsed": 1
  }
}

Verifica in blocco

3 endpoint in questo gruppo.

POST/v1/verify-batch

Invia un job di verifica in blocco

Invia fino a 50.000 email per job. L'elaborazione è asincrona, quindi interroga GET /v1/jobs/:jobId per vedere l'avanzamento. Invia un header Idempotency-Key per ripetere in sicurezza la creazione del job senza addebiti doppi.

Autorizzazioni

api_key_auth

Corpo della richiesta

emails

Obbligatorio

string[]

Array di indirizzi email da verificare. Massimo 50.000 per job. I duplicati e gli indirizzi con formato errato vengono rimossi dal server.

name

string

Etichetta leggibile opzionale per il job. Compare nella tua dashboard.

POST/v1/verify-batch

Esempi di risposta

{
  "success": true,
  "data": {
    "jobId": "api_job_6a627dd94559c7cd818d8fc9",
    "status": "processing",
    "name": "July prospect list",
    "submittedEmails": 19,
    "totalEmails": 19,
    "acceptedEmails": 19,
    "rejectedEmails": 0,
    "processedEmails": 0,
    "progress": { "total": 19, "processed": 0, "percentage": 0 },
    "requestId": "e8044428-e49f-4aa2-9900-e29d73fd4071",
    "batchIds": [
      "a639b1de-0e3a-4f8a-882d-95cee9db3f99",
      "c2760ed9-eced-4222-939b-3fa4151bde93"
    ],
    "createdAt": "2026-07-23T20:47:21.908Z",
    "updatedAt": "2026-07-23T20:47:22.040Z",
    "completedAt": null,
    "resultsExpiresAt": null,
    "resultsExpired": false,
    "error": null
  },
  "meta": {
    "idempotentReplay": false,
    "acceptedEmails": 19,
    "rejectedEmails": 0,
    "duplicateEmails": 0,
    "invalidEmails": 0
  }
}

GET/v1/jobs/:jobId

Ottieni lo stato di un job in blocco

Interroga questo endpoint per controllare l'avanzamento. Passaggi di stato: processing → completed (oppure failed). Intervallo consigliato tra le richieste: da 10 a 15 secondi. I batch piccoli (meno di 50 email) di solito finiscono entro 30 secondi.

Autorizzazioni

api_key_auth

Parametri di percorso e di query

jobId

Obbligatorio

string

L'ID del job restituito da POST /v1/verify-batch.

GET/v1/jobs/:jobId

Esempi di risposta

{
  "success": true,
  "data": {
    "jobId": "api_job_6a627dd94559c7cd818d8fc9",
    "status": "completed",
    "name": "July prospect list",
    "submittedEmails": 19,
    "totalEmails": 19,
    "acceptedEmails": 19,
    "rejectedEmails": 0,
    "processedEmails": 19,
    "progress": { "total": 19, "processed": 19, "percentage": 100 },
    "requestId": "e8044428-e49f-4aa2-9900-e29d73fd4071",
    "batchIds": [
      "a639b1de-0e3a-4f8a-882d-95cee9db3f99",
      "c2760ed9-eced-4222-939b-3fa4151bde93"
    ],
    "createdAt": "2026-07-23T20:47:21.908Z",
    "updatedAt": "2026-07-23T20:48:00.848Z",
    "completedAt": "2026-07-23T20:48:00.840Z",
    "resultsExpiresAt": "2026-07-25T20:48:00.840Z",
    "resultsExpired": false,
    "error": null
  }
}

GET/v1/jobs/:jobId/results

Ottieni i risultati di un job in blocco

Quando lo stato è "completed", recupera i risultati per ogni email. I risultati sono paginati, quindi invia i parametri di query page e limit. I risultati restano disponibili per 48 ore (vedi resultsExpiresAt nel job).

Autorizzazioni

api_key_auth

Parametri di percorso e di query

jobId

Obbligatorio

string

L'ID del job.

page

integer

Numero di pagina, predefinito 1.

limit

integer

Risultati per pagina, predefinito 25, massimo 500.

GET/v1/jobs/:jobId/results

Esempi di risposta

{
  "success": true,
  "data": {
    "job": {
      "jobId": "api_job_6a627dd94559c7cd818d8fc9",
      "status": "completed",
      "name": "July prospect list",
      "totalEmails": 19,
      "processedEmails": 19,
      "completedAt": "2026-07-23T20:48:00.840Z",
      "resultsExpiresAt": "2026-07-25T20:48:00.840Z"
    },
    "results": [
      {
        "email": "hassaan@giggal.ai",
        "status": "deliverable",
        "is_valid": true,
        "risk_level": "high",
        "deliverability_score": 88,
        "details": {
          "general": {
            "domain": "giggal.ai",
            "reason": "All validations passed"
          },
          "attributes": {
            "free_email": false,
            "role_account": false,
            "disposable": false,
            "catch_all": true,
            "has_plus_tag": false,
            "mailbox_full": false,
            "no_reply": false
          },
          "mail_server": {
            "smtp_provider": "google",
            "mx_record": "aspmx.l.google.com",
            "implicit_mx": null
          },
          "blacklist": {
            "is_blacklisted": false,
            "blacklists_found": [],
            "reputation_score": 100,
            "last_checked": "2026-07-23T20:47:22.665Z"
          },
          "sub_status": null
        }
      },
      {
        "email": "zain@giggal.ai",
        "status": "deliverable",
        "is_valid": true,
        "risk_level": "low",
        "deliverability_score": 100,
        "details": { "general": { "domain": "giggal.ai", "reason": "2.1.5 OK" }, "...": "..." }
      }
    ],
    "pagination": {
      "total": 19,
      "page": 1,
      "limit": 25,
      "pages": 1
    }
  }
}

Verifica catch-all

4 endpoint in questo gruppo.

POST/v1/catchall

Avvia un task di verifica catch-all

Avvia la verifica catch-all approfondita per un job in blocco completato. Vengono ricontrollati solo gli indirizzi segnati come catch-all nel job di origine. Costa 1 credito per indirizzo (vedi creditsRequired nella risposta).

Autorizzazioni

api_key_auth

Corpo della richiesta

jobId

Obbligatorio

string

L'ID di un job di verifica in blocco completato. Solo gli indirizzi catch-all di quel job ricevono la verifica approfondita.

name

string

Etichetta leggibile opzionale per il task.

POST/v1/catchall

Esempi di risposta

{
  "success": true,
  "data": {
    "taskId": "catchall_e4194da2-c118-47c2-84bf-9c25ce8a363e",
    "sourceJobId": "api_job_6a627dd94559c7cd818d8fc9",
    "fileId": "api_job_6a627dd94559c7cd818d8fc9",
    "status": "processing",
    "name": "Catch-all round for July list",
    "totalEmails": 8,
    "processedEmails": 0,
    "progress": { "total": 8, "processed": 0, "percentage": 0 },
    "requestId": "4e7596e0-c51e-4b05-b4e9-4b8a681041fd",
    "batchIds": ["7d2b1f03-68dd-4687-be95-fcc4fbabc2e7"],
    "creditsUsed": 0,
    "creditsRequired": 8,
    "creditsPerEmail": 1,
    "verdictCounts": { "valid": 0, "invalid": 0 },
    "initiatedVia": "developer_api",
    "createdAt": "2026-07-23T20:50:51.468Z",
    "updatedAt": "2026-07-23T20:50:51.662Z",
    "lastUpdated": "2026-07-23T20:50:51.468Z"
  },
  "meta": {
    "idempotentReplay": false
  }
}

GET/v1/catchall/:taskId

Ottieni lo stato di un task catch-all

Interroga questo endpoint per controllare l'avanzamento e i conteggi aggiornati in verdictCounts. I task catch-all di solito finiscono in un tempo che va da pochi secondi a pochi minuti, in base al volume.

Autorizzazioni

api_key_auth

Parametri di percorso e di query

taskId

Obbligatorio

string

L'ID del task restituito da POST /v1/catchall.

GET/v1/catchall/:taskId

Esempi di risposta

{
  "success": true,
  "data": {
    "taskId": "catchall_e4194da2-c118-47c2-84bf-9c25ce8a363e",
    "sourceJobId": "api_job_6a627dd94559c7cd818d8fc9",
    "fileId": "api_job_6a627dd94559c7cd818d8fc9",
    "status": "completed",
    "name": "Catch-all round for July list",
    "totalEmails": 8,
    "processedEmails": 8,
    "progress": { "total": 8, "processed": 8, "percentage": 100 },
    "requestId": "4e7596e0-c51e-4b05-b4e9-4b8a681041fd",
    "batchIds": ["7d2b1f03-68dd-4687-be95-fcc4fbabc2e7"],
    "creditsUsed": 8,
    "creditsRequired": 8,
    "creditsPerEmail": 1,
    "verdictCounts": { "valid": 1, "invalid": 7 },
    "initiatedVia": "developer_api",
    "createdAt": "2026-07-23T20:50:51.468Z",
    "updatedAt": "2026-07-23T20:50:56.646Z",
    "lastUpdated": "2026-07-23T20:50:56.583Z"
  }
}

GET/v1/catchall/:taskId/results

Ottieni i risultati di un task catch-all

Recupera i risultati paginati per ogni email, con il dettaglio del punteggio (segnali di analisi del dominio ed età del dominio).

Autorizzazioni

api_key_auth

Parametri di percorso e di query

taskId

Obbligatorio

string

L'ID del task.

page

integer

Numero di pagina, predefinito 1.

limit

integer

Risultati per pagina, predefinito 25, massimo 500.

verdict

string

Filtra per risultato: valid | invalid.

GET/v1/catchall/:taskId/results

Esempi di risposta

{
  "success": true,
  "data": {
    "task": {
      "taskId": "catchall_e4194da2-c118-47c2-84bf-9c25ce8a363e",
      "status": "completed",
      "totalEmails": 8,
      "verdictCounts": { "valid": 1, "invalid": 7 }
    },
    "results": [
      {
        "email": "hassaan@giggal.ai",
        "score": 88,
        "verdict": "valid",
        "is_actually_catchall": true,
        "breakdown": {
          "domain_triage": {
            "score": 16,
            "max": 25,
            "signals": [
              "provider:google",
              "auth:partial",
              "spf:strict",
              "mx:multiple",
              "ssl:valid",
              "a_records",
              "tld:trusted"
            ],
            "ssl_cert_age_days": 22
          },
          "domain_age": {
            "score": 12,
            "max": 15,
            "signals": ["age:9y"]
          }
        }
      },
      {
        "email": "zain@giggal.ai",
        "score": 9,
        "verdict": "invalid",
        "is_actually_catchall": true,
        "breakdown": {
          "domain_triage": {
            "score": 23,
            "max": 25,
            "signals": ["provider:google", "auth:spf+dkim+dmarc", "dmarc:reject"],
            "ssl_cert_age_days": 53
          },
          "domain_age": {
            "score": 15,
            "max": 15,
            "signals": ["age:11y"]
          }
        }
      }
    ],
    "pagination": {
      "total": 8,
      "page": 1,
      "limit": 25,
      "pages": 1
    }
  }
}

GET/v1/catchall/:taskId/download

Scarica i risultati catch-all in CSV

Scarica tutti i risultati di un task catch-all completato in un file CSV con le colonne Email, Score e Verdict. Il Content-Type è text/csv.

Autorizzazioni

api_key_auth

Parametri di percorso e di query

taskId

Obbligatorio

string

L'ID del task.

verdict

string

Filtra per risultato: valid | invalid.

GET/v1/catchall/:taskId/download

Esempi di risposta

Email,Score,Verdict
"hassaan@giggal.ai",88,"valid"
"zain@giggal.ai",9,"invalid"
"info@giggal.ai",8,"invalid"
"hassaan@giggal.ai",6,"invalid"
"zain@giggal.ai",3,"invalid"
"info@giggal.ai",8,"invalid"
"hassaan@giggal.ai",6,"invalid"
"zain@giggal.ai",9,"invalid"

Account

1 endpoint in questo gruppo.

GET/v1/credits

Ottieni il saldo crediti attuale

Restituisce il saldo del tuo account: crediti disponibili, riservati (bloccati per i job in corso) e totali storici. Le verifiche con risultato "unknown" vengono rimborsate in automatico e compaiono qui.

Autorizzazioni

api_key_auth

GET/v1/credits

Esempi di risposta

{
  "success": true,
  "data": {
    "balance": 145,
    "availableCredits": 145,
    "reservedCredits": 0,
    "totalPurchased": 1000,
    "totalConsumed": 92100,
    "transactionCount": 247,
    "lastTransactionAt": "2026-07-20T21:52:27.374Z"
  }
}

Errori e limiti di frequenza

Stato	Significato
200 OK	Richiesta riuscita (verifica sincrona o lettura di stato e risultati).
202 Accepted	Job o task asincrono creato e messo in coda.
400 Bad Request	Parametri mancanti o non validi (formato email errato, array emails vuoto, jobId mancante).
401 Unauthorized	Chiave API mancante, non valida o revocata.
402 Payment Required	Crediti insufficienti per l'operazione richiesta.
404 Not Found	L'ID del job o del task non esiste nel tuo account.
409 Conflict	Il job non è nello stato richiesto (per esempio, chiedi i risultati prima che finisca).
410 Gone	I risultati del job hanno superato il periodo di conservazione di 48 ore.
429 Too Many Requests	Limite di frequenza superato. Aspetta e riprova.
500 / 502 / 503	Il server o il servizio di verifica a monte non è disponibile per il momento.

Limiti di frequenza

Ogni risposta include gli header RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset (con le maiuscole dello standard RFC), così puoi regolare il ritmo delle richieste. RateLimit-Reset indica i secondi che mancano al reset della finestra attuale.

Categoria	Limite
Tutti gli endpoint (predefinito)	300 richieste / 15 minuti
Creazione di batch (POST /v1/verify-batch, POST /v1/catchall)	30 richieste / 15 minuti
Controllo dei job (GET /v1/jobs/:id, GET /v1/jobs/:id/results)	600 richieste / 15 minuti
Email massime per job in blocco	50.000
Conservazione dei risultati del job	48 ore

I limiti sono divisi in tre livelli perché i controlli di stato sono più frequenti della creazione di batch. Mentre un job è in corso puoi controllarlo ogni pochi secondi. Il limite di 600 / 15 min (circa 40 al minuto) ti lascia margine senza sovraccaricare il backend.

Ti servono limiti più alti?

Alziamo spesso i limiti per i partner di integrazione verificati.

Parla con noi

Formato della risposta 429

Quando superi un limite di frequenza, l'API restituisce HTTP 429 con questo corpo:

{
  "success": false,
  "message": "Developer API rate limit exceeded"
}

Prima di riprovare, aspetta il numero di secondi indicato nell'header RateLimit-Reset (i secondi che mancano al reset della finestra).

Pronto a integrare?

Crea la tua chiave API in pochi secondi. Sono inclusi crediti di prova gratuiti, così puoi provare l'integrazione completa prima di pagare.

Ottieni la tua chiave API Parla con il nostro team