API dokümanları

Genel REST API: kimlik doğrulama, uç noktalar, hata sözlüğü, sandbox anahtarı.

Kimlik doğrulama

Her istekte Authorization: Bearer <anahtar> başlığını gönder. Anahtarı giriş yaptığın oturumdan üretirsin (Ayarlar → API anahtarları). API anahtar üretmez, bu yüzden çalınan bir anahtar kendine yenisini ekleyemez.

curl https://your-domain.com/api/v1/verify \
  -H "Authorization: Bearer cl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"email":"name@example.com"}'

Sandbox anahtarı

cl_test_ ile başlayan anahtar worker'a ulaşmaz ve kredi harcamaz. Her statüyü denemek için şu test adreslerini gönder: ok@sandbox.test, invalid@sandbox.test, catch_all@sandbox.test, disposable@sandbox.test, role@sandbox.test, unknown@sandbox.test. Bunların dışındaki her adres unknown döner. Test anahtarı yanlışlıkla canlıda kalsa bile hiçbir gerçek adres onaylanmaz.

Uç noktalar

Yedi uç nokta var, hepsi bu sayfa gibi [locale] önekinin dışında:

POST	/api/v1/verify	Tekil e-posta doğrula, anında yanıt döner.
POST	/api/v1/lists	JSON dizisinden toplu liste oluştur.
GET	/api/v1/lists/:id	Bir listenin durumunu getir.
GET	/api/v1/lists/:id/results	Bir listenin sonuçlarını getir.
DELETE	/api/v1/lists/:id	Listeyi kalıcı olarak sil (GDPR).
GET	/api/v1/credits	Kalan kredi bakiyesini getir.
POST / GET / DELETE	/api/v1/webhooks	Webhook uç noktası kaydet, listele ya da sil.

Hata sözlüğü

Her hata aynı biçimde döner: { error: { code, message, request_id } }. code değeri aşağıdaki sabit listeden biridir.

unauthorized	401	Anahtar eksik ya da geçersiz.
forbidden	403	Anahtarın bu işlem için yetkisi yok (ör. yayınlanabilir anahtarla bakiye sorgusu).
not_found	404	Kayıt yok ya da sana ait değil. İkisinde de yanıt 404'tür, 403 verilmez.
invalid_request	400	Gövde beklenen şemaya uymuyor.
insufficient_credits	402	Kredi bakiyesi yetersiz.
rate_limited	429	İstek sınırı aşıldı. Retry-After başlığındaki süre kadar bekle.
too_large	413	Gövde boyutu sınırı aşıyor.
internal	500	Sunucu hatası, tekrar dene.

Idempotency

Idempotency-Key başlığı gönderirsen, aynı anahtarla gelen ikinci istek ilk başarılı yanıtı aynen döner. Hatalar saklanmaz: 4xx ya da 5xx sonrası aynı anahtar isteği yeniden çalıştırır. Aynı anahtarla farklı bir gövde gönderirsen 400 alırsın. İlk istek hâlâ sürüyorsa ikinci istek Retry-After: 1 ile 429 alır; tekrar dene, ilk yanıtı alırsın. Saklanan yanıtta e-posta adresi yer almaz.

İstek sınırı

Şu an her anahtar için dakikada 60 istek yapılabilir (kayan 60 saniyelik pencere). Sınır aşılırsa 429 ve Retry-After başlığı döner.

Tarayıcıdaki publishable anahtar ayrıca 24 saatte en fazla 500 doğrulama başlatır (varsayılan; API anahtarları ekranında değiştirirsin). Sınırı aşan istek 429 alır ve kredi harcamaz.

Hazır entegrasyonlar

API'yi doğrudan çağırmadan önce şunlara bak:

Zapier: Verify Email action'ı Sheets/CRM akışlarına tek tıkla eklenir.
Mailchimp senkronizasyonu: listeyi çek, doğrula, etiketleri geri yaz (Ayarlar → Entegrasyonlar).
Webhook: toplu iş bitince imzalı bir POST gelir (X-Clearlist-Signature).