Język

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

Szukasz ogólnego opisu? Zobacz stronę o API do weryfikacji e-mail albo o API do walidacji e-mail w formularzach rejestracji (po angielsku).

Email validator API: dokumentacja API do weryfikacji e-mail

Weryfikuj adres e-mail, uruchamiaj masową weryfikację i szczegółowo sprawdzaj adresy catch-all oraz adresy chronione przez SEG. Wszystkie endpointy używają formatu JSON i uwierzytelniania kluczem API. Płacisz tylko za udane weryfikacje.

Wprowadzenie

API Giggal.ai pozwala zweryfikować adres e-mail, uruchomić masową weryfikację do 50 000 adresów w jednym zadaniu oraz szczegółowo sprawdzić adresy catch-all i adresy chronione przez SEG. To proste API REST w formacie JSON. Każda udana weryfikacja zużywa kredyty z twojego konta.

Bazowy URL

https://api.giggal.ai/v1

Jak uzyskać klucz API

Utwórz klucz API w panelu Giggal.ai: otwórz zakładkę Developer API na pasku bocznym i kliknij Create API Key. Każdy klucz jest powiązany z twoim kontem i ma własne statystyki użycia. Możesz go unieważnić w każdej chwili.

Otwórz zakładkę Developer API

Format odpowiedzi

Każda odpowiedź ma tę samą strukturę JSON:

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

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

Szybki start: weryfikacja adresu w 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"}'

Uwierzytelnianie

Wysyłaj klucz API z każdym żądaniem, w jednym z dwóch nagłówków. Oba działają.

Opcja 1: token Bearer

Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx

Opcja 2: nagłówek X-API-Key

X-API-Key: tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx

Brak klucza albo klucz nieprawidłowy lub unieważniony zwraca błąd HTTP 401. Nigdy nie umieszczaj kluczy API w kodzie po stronie klienta. Wywołuj API przez swój backend.

Idempotencja (weryfikacja masowa i catch-all)

Do POST /v1/verify-batch i POST /v1/catchall dołącz nagłówek Idempotency-Key. Ponowna próba z tym samym kluczem zwraca pierwotną odpowiedź. Nie powstaje duplikat zadania, a kredyty nie są pobierane dwa razy.

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

Pojedyncza weryfikacja

1 endpoint w tej grupie.

POST/v1/verify

Weryfikacja adresu e-mail

Weryfikuje jeden adres e-mail synchronicznie. Kosztuje 1 kredyt. Jeśli domena jest typu catch-all, szczegółowe sprawdzenie odbywa się w tym samym żądaniu, a odpowiedź zawiera pola catch_all_score i catch_all_verdict.

Autoryzacja

api_key_auth

Treść żądania

Wymagany

string

Adres e-mail do weryfikacji.

POST/v1/verify

Przykładowe odpowiedzi

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

Masowa weryfikacja

Liczba endpointów w tej grupie: 3.

POST/v1/verify-batch

Wysłanie zadania wsadowego do masowej weryfikacji

Wyślij do 50 000 adresów w jednym zadaniu. Przetwarzanie jest asynchroniczne: odpytuj GET /v1/jobs/:jobId, aby śledzić postęp. Dołącz nagłówek Idempotency-Key, aby ponowić utworzenie zadania bez podwójnej opłaty.

Autoryzacja

api_key_auth

Treść żądania

emails

Wymagany

string[]

Lista adresów e-mail do weryfikacji. Maksymalnie 50 000 w jednym zadaniu. Duplikaty i błędnie zapisane adresy są usuwane po stronie serwera.

name

string

Opcjonalna nazwa zadania, czytelna dla człowieka. Widoczna w twoim panelu.

POST/v1/verify-batch

Przykładowe odpowiedzi

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

Odpytuj ten endpoint, aby śledzić postęp. Zmiana statusu: processing → completed (albo failed). Zalecany odstęp między zapytaniami: od 10 do 15 sekund. Małe listy (poniżej 50 adresów) kończą się zwykle w mniej niż 30 sekund.

Autoryzacja

api_key_auth

Parametry ścieżki i zapytania

jobId

Wymagany

string

Identyfikator zadania zwrócony przez POST /v1/verify-batch.

GET/v1/jobs/:jobId

Przykładowe odpowiedzi

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

Wyniki zadania wsadowego

Gdy status ma wartość "completed", pobierz wyniki dla każdego adresu. Wyniki są stronicowane: użyj parametrów zapytania page i limit. Wyniki są przechowywane przez 48 godzin (zobacz pole resultsExpiresAt w zadaniu).

Autoryzacja

api_key_auth

Parametry ścieżki i zapytania

jobId

Wymagany

string

Identyfikator zadania.

page

integer

Numer strony, domyślnie 1.

limit

integer

Liczba wyników na stronę, domyślnie 25, maksymalnie 500.

GET/v1/jobs/:jobId/results

Przykładowe odpowiedzi

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

Weryfikacja catch-all

Liczba endpointów w tej grupie: 4.

POST/v1/catchall

Uruchomienie zadania weryfikacji catch-all

Uruchamia szczegółową weryfikację catch-all dla zakończonego zadania wsadowego. Ponownie sprawdzane są tylko adresy oznaczone jako catch-all w pierwotnym zadaniu. Opłata wynosi 1 kredyt za adres (zobacz pole creditsRequired w odpowiedzi).

Autoryzacja

api_key_auth

Treść żądania

jobId

Wymagany

string

Identyfikator zakończonego zadania wsadowego do masowej weryfikacji. Szczegółowo sprawdzane są tylko adresy catch-all z tego zadania.

name

string

Opcjonalna nazwa zadania, czytelna dla człowieka.

POST/v1/catchall

Przykładowe odpowiedzi

{
  "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 zadania catch-all

Odpytuj ten endpoint, aby śledzić postęp i aktualne liczniki verdictCounts. Zadanie catch-all trwa zwykle od kilku sekund do kilku minut, zależnie od wolumenu.

Autoryzacja

api_key_auth

Parametry ścieżki i zapytania

taskId

Wymagany

string

Identyfikator zadania zwrócony przez POST /v1/catchall.

GET/v1/catchall/:taskId

Przykładowe odpowiedzi

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

Wyniki zadania catch-all

Pobiera stronicowane wyniki dla każdego adresu ze szczegółami oceny (sygnały sortowania domeny i wiek domeny).

Autoryzacja

api_key_auth

Parametry ścieżki i zapytania

taskId

Wymagany

string

Identyfikator zadania.

page

integer

Numer strony, domyślnie 1.

limit

integer

Liczba wyników na stronę, domyślnie 25, maksymalnie 500.

verdict

string

Filtr według wyniku: valid | invalid.

GET/v1/catchall/:taskId/results

Przykładowe odpowiedzi

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

Pobranie wyników catch-all w pliku CSV

Pobiera wszystkie wyniki zakończonego zadania catch-all w pliku CSV z kolumnami Email, Score i Verdict. Content-Type to text/csv.

Autoryzacja

api_key_auth

Parametry ścieżki i zapytania

taskId

Wymagany

string

Identyfikator zadania.

verdict

string

Filtr według wyniku: valid | invalid.

GET/v1/catchall/:taskId/download

Przykładowe odpowiedzi

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 endpoint w tej grupie.

GET/v1/credits

Saldo kredytów

Zwraca saldo konta: dostępne kredyty, kredyty zarezerwowane (zablokowane dla trwających zadań) i sumy od założenia konta. Kredyty za weryfikacje z wynikiem "unknown" wracają automatycznie i widać je tutaj.

Autoryzacja

api_key_auth

GET/v1/credits

Przykładowe odpowiedzi

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

Błędy i limity zapytań

Status	Znaczenie
200 OK	Żądanie się powiodło (weryfikacja synchroniczna albo odczyt statusu lub wyników).
202 Accepted	Zadanie asynchroniczne zostało utworzone i dodane do kolejki.
400 Bad Request	Brak parametrów lub nieprawidłowe parametry (zły format adresu, pusta lista emails, brak jobId).
401 Unauthorized	Brak klucza API albo klucz nieprawidłowy lub unieważniony.
402 Payment Required	Za mało kredytów na tę operację.
404 Not Found	Identyfikator zadania nie istnieje na twoim koncie.
409 Conflict	Zadanie nie jest w wymaganym stanie (na przykład wyniki pobrano przed jego zakończeniem).
410 Gone	Wyniki zadania przekroczyły okres przechowywania wynoszący 48 godzin.
429 Too Many Requests	Przekroczono limit zapytań. Odczekaj chwilę i spróbuj ponownie.
500 / 502 / 503	Serwer lub zewnętrzna usługa weryfikacji jest chwilowo niedostępna.

Limity zapytań

Każda odpowiedź zawiera nagłówki RateLimit-Limit, RateLimit-Remaining i RateLimit-Reset (pisownia według RFC). Pomagają one rozłożyć zapytania w czasie. RateLimit-Reset podaje liczbę sekund do wyzerowania bieżącego okna.

Kategoria	Limit
Wszystkie endpointy (domyślnie)	300 zapytań / 15 minut
Tworzenie zadań (POST /v1/verify-batch, POST /v1/catchall)	30 zapytań / 15 minut
Śledzenie zadań (GET /v1/jobs/:id, GET /v1/jobs/:id/results)	600 zapytań / 15 minut
Maksymalna liczba adresów w zadaniu wsadowym	50 000
Przechowywanie wyników	48 godzin

Są trzy poziomy limitów, bo zadanie sprawdza się częściej, niż się je tworzy. Podczas trwania zadania możesz odpytywać API co kilka sekund. Limit 600 / 15 min (około 40 na minutę) daje więc zapas i nie przeciąża serwera.

Potrzebujesz wyższych limitów?

Regularnie podnosimy limity dla zweryfikowanych partnerów integracyjnych.

Skontaktuj się z nami

Format odpowiedzi 429

Po przekroczeniu limitu API zwraca błąd HTTP 429 z taką treścią:

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

Przed ponowną próbą odczekaj liczbę sekund podaną w nagłówku RateLimit-Reset (czas do wyzerowania okna).

Chcesz zintegrować API?

Utwórz klucz API w kilka sekund. Na start dostajesz darmowe kredyty testowe, więc sprawdzisz całą integrację przed zakupem.

Uzyskaj klucz API Porozmawiaj z naszym zespołem