E-posta doğrulama API dokümantasyonu
Tek tek e-posta adreslerini doğrulayın, toplu doğrulama işleri çalıştırın ve catch-all ile SEG korumalı adresleri derinlemesine kontrol edin. Tüm endpointler JSON kullanır ve API anahtarıyla kimlik doğrulama yapar. Yalnızca başarılı doğrulamalar için ödeme yaparsınız.
Giriş
Giggal.ai API'si ile tek tek e-posta adreslerini doğrulayabilir, iş başına en fazla 50.000 e-posta adresi içeren toplu doğrulama işleri çalıştırabilir ve catch-all ile SEG korumalı adresleri derinlemesine kontrol edebilirsiniz. Bu, JSON kullanan basit bir REST API'dir. Her başarılı doğrulama hesabınızdan kredi kullanır.
https://api.giggal.ai/v1API anahtarınızı Giggal.ai panelinizden oluşturun: kenar çubuğunda Developer API sekmesini açın ve Create API Key düğmesine tıklayın. Her anahtar hesabınıza bağlıdır ve kendi kullanımını ayrı kaydeder. Bir anahtarı istediğiniz zaman iptal edebilirsiniz.
Developer API sekmesini açınHer yanıt aynı JSON yapısını kullanır:
// Success
{ "success": true, "data": { ... }, "meta": { ... } }
// Error
{ "success": false, "error": "Human-readable error message" }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"}'Kimlik doğrulama
API anahtarınızı her istekte aşağıdaki iki HTTP başlığından biriyle gönderin. İkisi de çalışır.
Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxxxxxxxX-API-Key: tp_live_xxxxxxxxxxxxxxxxxxxxxxxxxEksik, geçersiz veya iptal edilmiş anahtarlar HTTP 401 hatası döndürür. API anahtarlarını asla istemci tarafındaki kodda göstermeyin. API çağrılarını kendi sunucunuz üzerinden yapın.
POST /v1/verify-batch ve POST /v1/catchall isteklerinde bir Idempotency-Key başlığı gönderin. Aynı anahtarla yapılan tekrar denemeleri ilk yanıtı döndürür. Yinelenen bir iş oluşmaz ve krediler iki kez düşülmez.
Idempotency-Key: 2026-07-24-list-batch-42Tek adres doğrulama
Bu grupta 1 endpoint var.
/v1/verifyTek bir e-posta adresini doğrulama
Tek bir e-posta adresini eş zamanlı olarak doğrular. 1 kredi kullanır. Alan adı catch-all ise derinlemesine doğrulama aynı istekte çalışır ve yanıtta catch_all_score ile catch_all_verdict alanları bulunur.
Toplu doğrulama
Bu grupta 3 endpoint var.
/v1/verify-batchToplu doğrulama işi gönderme
İş başına en fazla 50.000 e-posta adresi gönderin. İşlem eş zamansızdır. İlerlemeyi görmek için GET /v1/jobs/:jobId adresini düzenli olarak sorgulayın. İşi oluşturma isteğini iki kez ücretlendirilmeden güvenle tekrar denemek için bir Idempotency-Key başlığı gönderin.
/v1/jobs/:jobIdToplu işin durumunu alma
İlerlemeyi görmek için düzenli olarak sorgulayın. Durum processing değerinden completed (veya failed) değerine geçer. Önerilen sorgulama aralığı: 10 ila 15 saniye. Küçük listeler (50 adresten az) genellikle 30 saniye içinde tamamlanır.
/v1/jobs/:jobId/resultsToplu işin sonuçlarını alma
Durum "completed" olduğunda her e-posta adresinin sonucunu alın. Sonuçlar sayfalara bölünür, bu yüzden page ve limit query parametrelerini gönderin. Sonuçlar 48 saat saklanır (işteki resultsExpiresAt alanına bakın).
Catch-all doğrulama
Bu grupta 4 endpoint var.
/v1/catchallCatch-all doğrulama görevi başlatma
Tamamlanmış bir toplu iş için derinlemesine catch-all doğrulamasını başlatır. Yalnızca kaynak işte catch-all olarak işaretlenen adresler yeniden kontrol edilir. Adres başına 1 kredi ücretlendirilir (yanıttaki creditsRequired alanına bakın).
/v1/catchall/:taskIdCatch-all görevinin durumunu alma
İlerlemeyi ve güncel verdictCounts sayılarını görmek için düzenli olarak sorgulayın. Catch-all görevleri, adres sayısına bağlı olarak genellikle birkaç saniye ila birkaç dakika içinde tamamlanır.
/v1/catchall/:taskId/resultsCatch-all görevinin sonuçlarını alma
Her e-posta adresinin sonucunu, puanın dayandığı ayrıntılarla (alan adı sinyalleri ve alan adının yaşı) birlikte sayfalar hâlinde alır.
/v1/catchall/:taskId/downloadCatch-all sonuçlarını CSV olarak indirme
Tamamlanmış bir catch-all görevinin tüm sonuçlarını Email, Score ve Verdict sütunlarını içeren bir CSV dosyası olarak indirir. Content-Type değeri text/csv olur.
Hesap
Bu grupta 1 endpoint var.
/v1/creditsGüncel kredi bakiyesini alma
Hesap bakiyenizi döndürür: kullanılabilir krediler, ayrılmış krediler (devam eden işler için tutulanlar) ve hesabın açılışından bu yana toplamlar. "unknown" sonucuyla dönen doğrulamalar otomatik olarak iade edilir ve burada görünür.
Hatalar ve istek sınırları
| Durum | Anlamı |
|---|---|
| 200 OK | İstek başarılı oldu (eş zamanlı doğrulama veya durum ya da sonuç sorgusu). |
| 202 Accepted | Eş zamansız iş veya görev oluşturuldu ve sıraya alındı. |
| 400 Bad Request | Eksik veya geçersiz parametreler (hatalı e-posta biçimi, boş emails dizisi, eksik jobId). |
| 401 Unauthorized | API anahtarı eksik, geçersiz veya iptal edilmiş. |
| 402 Payment Required | İstenen işlem için kredi yetersiz. |
| 404 Not Found | Bu iş veya görev kimliği hesabınızda yok. |
| 409 Conflict | İş gerekli durumda değil (örneğin iş tamamlanmadan sonuçların istenmesi). |
| 410 Gone | İş sonuçlarının 48 saatlik saklama süresi doldu. |
| 429 Too Many Requests | İstek sınırı aşıldı. Bir süre bekleyin ve tekrar deneyin. |
| 500 / 502 / 503 | Sunucu veya arkadaki doğrulama hizmeti geçici olarak kullanılamıyor. |
İstek sınırları
Her yanıtta RateLimit-Limit, RateLimit-Remaining ve RateLimit-Reset başlıkları bulunur (RFC yazımıyla). Böylece isteklerinizin hızını ayarlayabilirsiniz. RateLimit-Reset, geçerli zaman aralığı sıfırlanana kadar kalan saniye sayısıdır.
| Kategori | Sınır |
|---|---|
| Tüm endpointler (varsayılan) | 300 istek / 15 dakika |
| İş oluşturma (POST /v1/verify-batch, POST /v1/catchall) | 30 istek / 15 dakika |
| İş durumu sorgulama (GET /v1/jobs/:id, GET /v1/jobs/:id/results) | 600 istek / 15 dakika |
| Toplu iş başına en fazla e-posta adresi | 50.000 |
| İş sonuçlarının saklanma süresi | 48 saat |
Üç ayrı sınır vardır, çünkü işin durumunu sorgulamak iş oluşturmaktan çok daha sık yapılır. Bir iş çalışırken birkaç saniyede bir sorgu gönderebilirsiniz. 600 / 15 min sınırı (dakikada yaklaşık 40) size sunucuyu zorlamadan yeterli alan bırakır.
Daha yüksek sınırlara mı ihtiyacınız var?
Doğrulanmış entegrasyon ortakları için sınırları düzenli olarak yükseltiyoruz.
429 yanıtının biçimi
Bir istek sınırına ulaştığınızda API, aşağıdaki gövdeyle HTTP 429 döndürür:
{
"success": false,
"message": "Developer API rate limit exceeded"
}Tekrar denemeden önce RateLimit-Reset başlığındaki değer kadar (zaman aralığı sıfırlanana kadar kalan saniye) bekleyin.
Entegrasyona hazır mısınız?
API anahtarınızı saniyeler içinde oluşturun. Ücretsiz deneme kredileri dahildir. Böylece ödeme yapmadan önce entegrasyonu baştan sona kurup test edebilirsiniz.
