Taal

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

Zoek je een algemeen overzicht? Lees de pagina over de API voor e-mailverificatie of over de API voor e-mailvalidatie in aanmeldformulieren (in het Engels).

API-documentatie voor e-mailverificatie

Controleer een e-mailadres, start bulkcontroles en controleer catch-all-adressen en adressen achter een SEG grondig. Alle endpoints gebruiken JSON en authenticatie met een API-sleutel. Je betaalt alleen voor geslaagde controles.

Introductie

Met de API van Giggal.ai controleer je een e-mailadres, start je bulkcontroles tot 50.000 e-mailadressen per taak en controleer je catch-all-adressen en adressen achter een SEG grondig. Het is een eenvoudige REST API met JSON. Elke geslaagde controle gebruikt credits van je account.

Basis-URL

https://api.giggal.ai/v1

Een API-sleutel aanmaken

Maak een API-sleutel aan in je Giggal.ai-dashboard: open het tabblad Developer API in de zijbalk en klik op Create API Key. Elke sleutel hoort bij je account en houdt zijn eigen gebruik bij. Je kunt een sleutel op elk moment intrekken.

Tabblad Developer API openen

Opbouw van het antwoord

Elk antwoord heeft dezelfde JSON-structuur:

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

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

Snel starten: een adres controleren met 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"}'

Authenticatie

Stuur je API-sleutel mee met elk verzoek, in een van deze twee headers. Beide werken.

Optie 1: Bearer-token

Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx

Optie 2: header X-API-Key

X-API-Key: tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx

Een ontbrekende, ongeldige of ingetrokken sleutel geeft een HTTP 401-fout. Zet je API-sleutels nooit in code aan de clientkant. Stuur de aanroepen via je eigen backend.

Idempotentie (bulk en catch-all)

Stuur bij POST /v1/verify-batch en POST /v1/catchall een header Idempotency-Key mee. Een nieuwe poging met dezelfde sleutel geeft het oorspronkelijke antwoord terug. Er ontstaat geen dubbele taak en de credits worden niet twee keer afgeschreven.

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

Losse controle

1 endpoint in deze groep.

POST/v1/verify

Een e-mailadres controleren

Controleert één e-mailadres synchroon. Kost 1 credit. Is het domein catch-all, dan gebeurt de grondige controle in hetzelfde verzoek en bevat het antwoord catch_all_score en catch_all_verdict.

Autorisatie

api_key_auth

Body van het verzoek

Verplicht

string

Het e-mailadres dat je wilt controleren.

POST/v1/verify

Voorbeelden van antwoorden

{
  "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
  }
}

Bulkcontrole

3 endpoints in deze groep.

POST/v1/verify-batch

Een bulkcontrole starten

Stuur tot 50.000 e-mailadressen per taak. De verwerking is asynchroon: vraag GET /v1/jobs/:jobId op om de voortgang te volgen. Stuur een header Idempotency-Key mee om het aanmaken van een taak opnieuw te proberen zonder dubbele kosten.

Autorisatie

api_key_auth

Body van het verzoek

emails

Verplicht

string[]

Lijst met e-mailadressen om te controleren. Maximaal 50.000 per taak. Dubbele en verkeerd opgebouwde adressen haalt de server eruit.

name

string

Optionele naam voor de taak, leesbaar voor mensen. Wordt getoond in je dashboard.

POST/v1/verify-batch

Voorbeelden van antwoorden

{
  "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

Status van een bulktaak opvragen

Vraag dit endpoint op om de voortgang te volgen. De status gaat van processing naar completed (of failed). Aanbevolen interval: elke 10 tot 15 seconden. Kleine lijsten (minder dan 50 e-mailadressen) zijn meestal binnen 30 seconden klaar.

Autorisatie

api_key_auth

Pad- en queryparameters

jobId

Verplicht

string

De taak-ID die POST /v1/verify-batch teruggaf.

GET/v1/jobs/:jobId

Voorbeelden van antwoorden

{
  "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

Resultaten van een bulktaak opvragen

Als de status "completed" is, haal je de resultaten per e-mailadres op. De resultaten zijn verdeeld over pagina’s: stuur de queryparameters page en limit mee. Resultaten worden 48 uur bewaard (zie resultsExpiresAt bij de taak).

Autorisatie

api_key_auth

Pad- en queryparameters

jobId

Verplicht

string

De ID van de taak.

page

integer

Paginanummer, standaard 1.

limit

integer

Resultaten per pagina, standaard 25, maximaal 500.

GET/v1/jobs/:jobId/results

Voorbeelden van antwoorden

{
  "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
    }
  }
}

Catch-all-controle

4 endpoints in deze groep.

POST/v1/catchall

Een catch-all-controle starten

Start de grondige catch-all-controle voor een afgeronde bulktaak. Alleen de adressen die in de oorspronkelijke taak als catch-all zijn gemarkeerd, worden opnieuw gecontroleerd. Kost 1 credit per adres (zie creditsRequired in het antwoord).

Autorisatie

api_key_auth

Body van het verzoek

jobId

Verplicht

string

De ID van een afgeronde bulktaak. Alleen de catch-all-adressen uit die taak worden grondig gecontroleerd.

name

string

Optionele naam voor de taak, leesbaar voor mensen.

POST/v1/catchall

Voorbeelden van antwoorden

{
  "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

Status van een catch-all-taak opvragen

Vraag dit endpoint op om de voortgang en de bijgewerkte tellingen in verdictCounts te volgen. Een catch-all-taak duurt meestal een paar seconden tot een paar minuten, afhankelijk van het aantal adressen.

Autorisatie

api_key_auth

Pad- en queryparameters

taskId

Verplicht

string

De taak-ID die POST /v1/catchall teruggaf.

GET/v1/catchall/:taskId

Voorbeelden van antwoorden

{
  "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

Resultaten van een catch-all-taak opvragen

Haalt de resultaten per e-mailadres op, verdeeld over pagina’s, met de opbouw van de score (signalen van het domein en de leeftijd van het domein).

Autorisatie

api_key_auth

Pad- en queryparameters

taskId

Verplicht

string

De ID van de taak.

page

integer

Paginanummer, standaard 1.

limit

integer

Resultaten per pagina, standaard 25, maximaal 500.

verdict

string

Filteren op resultaat: valid | invalid.

GET/v1/catchall/:taskId/results

Voorbeelden van antwoorden

{
  "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

Catch-all-resultaten downloaden als CSV

Downloadt alle resultaten van een afgeronde catch-all-taak als CSV-bestand met de kolommen Email, Score en Verdict. Het Content-Type is text/csv.

Autorisatie

api_key_auth

Pad- en queryparameters

taskId

Verplicht

string

De ID van de taak.

verdict

string

Filteren op resultaat: valid | invalid.

GET/v1/catchall/:taskId/download

Voorbeelden van antwoorden

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 deze groep.

GET/v1/credits

Saldo van je credits opvragen

Geeft het saldo van je account: beschikbare credits, gereserveerde credits (vastgezet voor lopende taken) en totalen sinds het openen van je account. Controles met het resultaat "unknown" worden automatisch terugbetaald en staan hier ook.

Autorisatie

api_key_auth

GET/v1/credits

Voorbeelden van antwoorden

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

Fouten en limieten

Status	Betekenis
200 OK	Het verzoek is gelukt (synchrone controle, of het opvragen van een status of resultaten).
202 Accepted	De asynchrone taak is aangemaakt en staat in de wachtrij.
400 Bad Request	Parameters ontbreken of zijn ongeldig (verkeerd e-mailformaat, lege lijst emails, jobId ontbreekt).
401 Unauthorized	API-sleutel ontbreekt, is ongeldig of is ingetrokken.
402 Payment Required	Niet genoeg credits voor deze actie.
404 Not Found	Deze taak-ID bestaat niet in je account.
409 Conflict	De taak heeft niet de vereiste status (bijvoorbeeld resultaten opgevraagd voordat de taak klaar is).
410 Gone	De resultaten van de taak zijn ouder dan de bewaartermijn van 48 uur.
429 Too Many Requests	Limiet voor verzoeken overschreden. Wacht even en probeer het opnieuw.
500 / 502 / 503	De server of de onderliggende verificatiedienst is tijdelijk niet beschikbaar.

Limieten voor verzoeken

Elk antwoord bevat de headers RateLimit-Limit, RateLimit-Remaining en RateLimit-Reset (schrijfwijze volgens de RFC), zodat je je verzoeken kunt spreiden. RateLimit-Reset geeft het aantal seconden tot het huidige venster opnieuw begint.

Categorie	Limiet
Alle endpoints (standaard)	300 verzoeken / 15 minuten
Taken aanmaken (POST /v1/verify-batch, POST /v1/catchall)	30 verzoeken / 15 minuten
Taken volgen (GET /v1/jobs/:id, GET /v1/jobs/:id/results)	600 verzoeken / 15 minuten
Maximaal aantal e-mailadressen per bulktaak	50.000
Bewaartermijn van resultaten	48 uur

Er zijn drie limieten, omdat je een taak vaker volgt dan dat je er een aanmaakt. Je kunt de API elke paar seconden opvragen terwijl een taak loopt. De limiet van 600 / 15 min (ongeveer 40 per minuut) geeft je dus genoeg ruimte zonder de server te overbelasten.

Hogere limieten nodig?

We verhogen de limieten regelmatig voor geverifieerde integratiepartners.

Neem contact op

Opbouw van het 429-antwoord

Als je een limiet bereikt, geeft de API een HTTP 429-fout met deze body:

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

Wacht voor een nieuwe poging het aantal seconden dat in de header RateLimit-Reset staat (de tijd tot het venster opnieuw begint).

Klaar om de API te koppelen?

Maak in een paar seconden je API-sleutel aan. Gratis proefcredits zitten erbij, zodat je alles van begin tot eind kunt testen voordat je betaalt.

Je API-sleutel aanmaken Praat met ons team