Sprache

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

Sie suchen einen Überblick? Lesen Sie die Seite zur API für E-Mail-Verifizierung oder zur API für E-Mail-Validierung in Anmeldeformularen.

Dokumentation der API für E-Mail-Verifizierung

Prüfen Sie einzelne E-Mails, starten Sie Massenprüfungen in Batches und prüfen Sie Catch-all-Adressen und Adressen hinter Sicherheits-Gateways (SEG) im Detail. Alle Endpunkte nutzen JSON und werden per API-Schlüssel authentifiziert. Abgerechnet wird nur jede erfolgreiche Prüfung.

Einführung

Mit der API von Giggal.ai prüfen Sie einzelne E-Mail-Adressen und starten Batches mit bis zu 50.000 E-Mails pro Job. Catch-all-Adressen und Adressen hinter Sicherheits-Gateways (SEG) prüfen Sie im Detail. Das alles läuft über eine einfache JSON-REST-API. Jede erfolgreiche Prüfung kostet Credits aus Ihrem Konto.

Basis-URL

https://api.giggal.ai/v1

API-Schlüssel erstellen

Erstellen Sie einen API-Schlüssel in Ihrem Giggal.ai-Dashboard. Öffnen Sie in der Seitenleiste den Tab Developer API und klicken Sie auf Create API Key. Jeder Schlüssel gehört zu Ihrem Konto, erfasst seine eigene Nutzung und lässt sich jederzeit widerrufen.

Tab Developer API öffnen

Antwortformat

Jede Antwort folgt demselben JSON-Format:

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

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

Schnellstart: eine E-Mail mit cURL prüfen

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

Authentifizierung

Senden Sie Ihren API-Schlüssel bei jeder Anfrage in einem von zwei Headern. Beide funktionieren.

Option 1: Bearer-Token

Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx

Option 2: Header X-API-Key

X-API-Key: tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx

Fehlende, ungültige oder widerrufene Schlüssel liefern HTTP 401. Legen Sie API-Schlüssel nie im clientseitigen Code offen. Leiten Sie die Aufrufe stattdessen über Ihr Backend.

Idempotenz (Massenprüfung und Catch-all)

Senden Sie bei POST /v1/verify-batch und POST /v1/catchall einen Header Idempotency-Key. Eine Wiederholung mit demselben Schlüssel liefert die ursprüngliche Antwort. Es entsteht kein doppelter Job, und es werden keine Credits doppelt abgebucht.

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

Einzelprüfung

1 Endpunkt in dieser Gruppe.

POST/v1/verify

Eine einzelne E-Mail prüfen

Prüft eine E-Mail-Adresse synchron. Kostet 1 Credit. Ist die Domain Catch-all, läuft die Tiefenprüfung direkt mit, und die Antwort enthält catch_all_score und catch_all_verdict.

Autorisierung

api_key_auth

Request-Body

Pflichtfeld

string

Die E-Mail-Adresse, die geprüft werden soll.

POST/v1/verify

Beispielantworten

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

Massenprüfung

3 Endpunkte in dieser Gruppe.

POST/v1/verify-batch

Einen Job zur Massenprüfung senden

Senden Sie bis zu 50.000 E-Mails pro Job. Die Verarbeitung läuft asynchron. Fragen Sie den Fortschritt über GET /v1/jobs/:jobId ab. Mit einem Header Idempotency-Key können Sie das Anlegen eines Jobs sicher wiederholen, ohne doppelte Kosten.

Autorisierung

api_key_auth

Request-Body

emails

Pflichtfeld

string[]

Array der E-Mail-Adressen, die geprüft werden sollen. Maximal 50.000 pro Job. Doppelte und fehlerhafte Adressen entfernt der Server.

name

string

Optionaler, lesbarer Name für den Job. Er wird in Ihrem Dashboard angezeigt.

POST/v1/verify-batch

Beispielantworten

{
  "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 eines Massenjobs abrufen

Fragen Sie diesen Endpunkt ab, um den Fortschritt zu prüfen. Statuswechsel: processing → completed (oder failed). Empfohlener Abstand zwischen Abfragen: 10 bis 15 Sekunden. Kleine Batches (unter 50 E-Mails) sind meist innerhalb von 30 Sekunden fertig.

Autorisierung

api_key_auth

Pfad- und Query-Parameter

jobId

Pflichtfeld

string

Die Job-ID, die POST /v1/verify-batch zurückgegeben hat.

GET/v1/jobs/:jobId

Beispielantworten

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

Ergebnisse eines Massenjobs abrufen

Sobald der Status "completed" ist, rufen Sie die Ergebnisse pro E-Mail ab. Die Ergebnisse sind seitenweise aufgeteilt. Übergeben Sie dazu die Query-Parameter page und limit. Die Ergebnisse werden 48 Stunden gespeichert (siehe resultsExpiresAt im Job).

Autorisierung

api_key_auth

Pfad- und Query-Parameter

jobId

Pflichtfeld

string

Die Job-ID.

page

integer

Seitennummer, Standard ist 1.

limit

integer

Ergebnisse pro Seite, Standard ist 25, maximal 500.

GET/v1/jobs/:jobId/results

Beispielantworten

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

4 Endpunkte in dieser Gruppe.

POST/v1/catchall

Eine Catch-all-Prüfung starten

Startet die Catch-all-Tiefenprüfung für einen abgeschlossenen Massenjob. Nur Adressen, die im ursprünglichen Job als Catch-all markiert sind, werden erneut geprüft. Abgerechnet wird 1 Credit pro Adresse (siehe creditsRequired in der Antwort).

Autorisierung

api_key_auth

Request-Body

jobId

Pflichtfeld

string

Die ID eines abgeschlossenen Massenjobs. Nur die Catch-all-Adressen aus diesem Job werden im Detail geprüft.

name

string

Optionaler, lesbarer Name für die Aufgabe.

POST/v1/catchall

Beispielantworten

{
  "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 einer Catch-all-Aufgabe abrufen

Fragen Sie diesen Endpunkt ab, um den Fortschritt und die laufend aktualisierten verdictCounts zu sehen. Catch-all-Aufgaben sind je nach Menge meist nach wenigen Sekunden bis wenigen Minuten fertig.

Autorisierung

api_key_auth

Pfad- und Query-Parameter

taskId

Pflichtfeld

string

Die Task-ID, die POST /v1/catchall zurückgegeben hat.

GET/v1/catchall/:taskId

Beispielantworten

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

Ergebnisse einer Catch-all-Aufgabe abrufen

Ruft die Ergebnisse pro E-Mail seitenweise ab, mit der zugrunde liegenden Aufschlüsselung des Scores (Signale aus der Domain-Prüfung und Alter der Domain).

Autorisierung

api_key_auth

Pfad- und Query-Parameter

taskId

Pflichtfeld

string

Die Task-ID.

page

integer

Seitennummer, Standard ist 1.

limit

integer

Ergebnisse pro Seite, Standard ist 25, maximal 500.

verdict

string

Nach Ergebnis filtern: valid | invalid.

GET/v1/catchall/:taskId/results

Beispielantworten

{
  "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-Ergebnisse als CSV herunterladen

Lädt alle Ergebnisse einer abgeschlossenen Catch-all-Aufgabe als CSV-Datei mit den Spalten Email, Score und Verdict herunter. Der Content-Type ist text/csv.

Autorisierung

api_key_auth

Pfad- und Query-Parameter

taskId

Pflichtfeld

string

Die Task-ID.

verdict

string

Nach Ergebnis filtern: valid | invalid.

GET/v1/catchall/:taskId/download

Beispielantworten

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"

Konto

1 Endpunkt in dieser Gruppe.

GET/v1/credits

Aktuelles Credit-Guthaben abrufen

Liefert Ihr Kontoguthaben mit verfügbaren Credits, reservierten Credits (für laufende Jobs zurückgehalten) und Gesamtwerten seit Kontoeröffnung. Prüfungen mit dem Ergebnis "unknown" werden automatisch erstattet und hier berücksichtigt.

Autorisierung

api_key_auth

GET/v1/credits

Beispielantworten

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

Fehler und Rate-Limits

Status	Bedeutung
200 OK	Anfrage erfolgreich (synchrone Prüfung oder Abruf von Status oder Ergebnissen).
202 Accepted	Asynchroner Job oder Aufgabe angelegt und in die Warteschlange gestellt.
400 Bad Request	Fehlende oder ungültige Parameter (falsches E-Mail-Format, leeres Array emails, fehlende jobId).
401 Unauthorized	Fehlender, ungültiger oder widerrufener API-Schlüssel.
402 Payment Required	Nicht genug Credits für die angefragte Aktion.
404 Not Found	Die Job- oder Task-ID existiert in Ihrem Konto nicht.
409 Conflict	Der Job hat nicht den nötigen Status (zum Beispiel Abruf von Ergebnissen vor dem Abschluss).
410 Gone	Die Ergebnisse des Jobs sind älter als die Speicherdauer von 48 Stunden.
429 Too Many Requests	Rate-Limit überschritten. Warten Sie und versuchen Sie es erneut.
500 / 502 / 503	Der Server oder der vorgelagerte Prüfdienst ist vorübergehend nicht erreichbar.

Rate-Limits

Jede Antwort enthält die Header RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset (Schreibweise nach RFC). So können Sie Ihre Anfragen takten. RateLimit-Reset ist die Anzahl der Sekunden, bis das aktuelle Zeitfenster zurückgesetzt wird.

Kategorie	Limit
Alle Endpunkte (Standard)	300 Anfragen / 15 Minuten
Anlegen von Batches (POST /v1/verify-batch, POST /v1/catchall)	30 Anfragen / 15 Minuten
Abfrage von Jobs (GET /v1/jobs/:id, GET /v1/jobs/:id/results)	600 Anfragen / 15 Minuten
Maximale E-Mails pro Massenjob	50.000
Speicherdauer der Job-Ergebnisse	48 Stunden

Die Limits sind in drei Stufen aufgeteilt, weil Statusabfragen häufiger vorkommen als das Anlegen von Batches. Während ein Job läuft, fragen Sie vielleicht alle paar Sekunden ab. Das Limit von 600 / 15 min (etwa 40 pro Minute) lässt Ihnen Spielraum, ohne das Backend zu überlasten.

Sie brauchen höhere Limits?

Für geprüfte Integrationspartner heben wir die Limits regelmäßig an.

Sprechen Sie uns an

Format der Antwort 429

Wenn Sie ein Rate-Limit erreichen, liefert die API HTTP 429 mit diesem Body:

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

Warten Sie vor einem neuen Versuch so lange, wie der Header RateLimit-Reset angibt (Sekunden bis zum Zurücksetzen des Zeitfensters).

Bereit für die Integration?

Erstellen Sie Ihren API-Schlüssel in wenigen Sekunden. Kostenlose Test-Credits sind inklusive. So können Sie die Integration vollständig aufbauen, bevor Sie etwas bezahlen.

API-Schlüssel erstellen Mit unserem Team sprechen