E-posta Kontrolü API Referansı

Kimlik doğrulama

POST /v1/email/validate, X-Api-Key başlığı üzerinden origin'e kilitli yayınlanabilir bir anahtar kabul eder — GET /v1/geo ile aynı anahtar türü ve izin verilen origin modeli. Bu sayfadaki diğer tüm uç noktalar (toplu, liste işleri, kayıt kontrolü) çok sayıda adres veya rastgele bir IP kabul ettiğinden, Authorization: Bearer üzerinden gizli anahtarınızı gerektirir ve yalnızca arka ucunuzdan çağrılmalıdır; yayınlanabilir bir anahtar orada 403 alır.

Örnek

curl https://api.watch-ip.com/v1/email/validate \
  -H "X-Api-Key: YOUR_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "John.Doe+news@Gmial.com"}'

{
  "email": "John.Doe+news@Gmial.com",
  "domain": "gmial.com",
  "syntaxValid": true,
  "isDisposable": false,
  "normalizedEmail": "john.doe+news@gmial.com",
  "canonicalEmail": "john.doe@gmial.com",
  "disposableSource": null,
  "isFreeProvider": false,
  "isRoleAccount": false,
  "didYouMean": "john.doe+news@gmail.com",
  "mx": {
    "status": "none",
    "host": null
  },
  "verdict": "reject",
  "reasons": [
    "no_mail_server",
    "typo_suspected"
  ]
}

Kararlar ve gerekçe kodları

Her koşul bir asgari karar belirler; en ağırı geçerli olur ve reasons, en ağırı önce gelecek şekilde hepsini listeler. Ücretsiz sağlayıcı adresinin kabul edilebilir olup olmadığı size bırakılmıştır — kararı asla değiştirmez.

Toplu kontrol

POST/v1/email/batch

Tek bir istekte 1–100 adresi, POST /v1/email/validate ile aynı kontroller ve aynı sonuç yapısıyla kontrol eder; giriş sırasına göre adres başına bir sonuç döner. { "emails": [...] } gönderin. Aynı alan adındaki adresler tek bir DNS sorgusunu paylaşır. Aylık plan kotanızdan adres başına bir istek düşülür; kotayı aşacak bir toplu istek 429 monthly_limit_exceeded ile bütünüyle reddedilir. Dakika başına hız sınırı açısından çağrının tamamı tek bir istek sayılır. Yalnızca gizli anahtar.

curl https://api.watch-ip.com/v1/email/batch \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["user@gmail.com", "someone@mailinator.com"]}'

{
  "results": [
    { "email": "user@gmail.com", "verdict": "accept", "reasons": [], ... },
    { "email": "someone@mailinator.com", "isDisposable": true, "disposableSource": "list", "verdict": "reject", "reasons": ["disposable_domain"], ... }
  ]
}

E-posta liste işleri

POST/v1/email/jobs

Arka planda 100.000'e kadar adresi kontrol eder. JSON { "emails": [...], "filename": "..." } veya en fazla 10 MB'lık bir text/csv gövdesi gönderin: başlığı email (ayrıca e-mail, email address, email_address veya mail; büyük/küçük harf duyarsız) olan sütun kullanılır, hiçbir başlık bunu belirtmiyorsa ilk sütun kullanılır; virgül, noktalı virgül ve sekme ayırıcıları algılanır. İş, oluşturulduğu anda ücretlendirilir — farklı her adres için bir istek (tam eşleşme), yani yinelenen adresler kontrol edilir ama bir kez ücretlendirilir — ve aylık kotanızı aşacak bir liste bütünüyle reddedilir. Bir işin bir kısmı yeniden denemelerden sonra işlenemezse iş failed olarak işaretlenir ve işlenmeyen kısmın kredileri iade edilir. İş nesnesiyle birlikte 202 yanıtı verir. Yalnızca gizli anahtar; aynı işler kontrol panelindeki Email lists sayfasından da yüklenip indirilebilir.

curl https://api.watch-ip.com/v1/email/jobs \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary @newsletter.csv

{
  "id": "5b0d6f5e-8a51-4f7e-9d0e-2c1f3f7f8a11",
  "status": "queued",
  "source": "api",
  "filename": null,
  "total": 12840,
  "credits": 12512,
  "processed": 0,
  "summary": null,
  "createdAt": "2026-09-28T10:00:00.000Z",
  "completedAt": null,
  "expiresAt": "2026-10-05T10:00:00.000Z"
}

İş durumu

GET/v1/email/jobs/{id}

Aynı iş nesnesini döndürür. status completed olana kadar yoklayın; yoklama ücretlendirilmez.

İş sonuçları

GET/v1/email/jobs/{id}/results

Gönderilen her satır için bir satır içeren, gönderim sırasına göre (yinelenenler dahil) bir CSV indirir. Sütunlar: email, normalized_email, verdict, reasons, syntax_valid, is_disposable, disposable_source, is_free_provider, is_role_account, did_you_mean, mx_status, mx_host. reasons noktalı virgülle ayrılır, boş hücreler null anlamına gelir ve sözdizimi geçersiz adreslerde mx_status boştur (hiçbir sorgu yapılmadı). =, +, - veya @ ile başlayan geçersiz bir adresin önüne, elektronik tablo uygulamaları onu formül olarak çalıştırmasın diye bir kesme işareti eklenir. İş tamamlanana kadar 409, süresi dolduktan sonra 410. İndirme ücretlendirilmez.

curl https://api.watch-ip.com/v1/email/jobs/5b0d6f5e-8a51-4f7e-9d0e-2c1f3f7f8a11/results \
  -H "Authorization: Bearer YOUR_SECRET_KEY" -o results.csv

Kayıt kontrolü

POST/v1/signup/check

Bir kaydı e-posta adresi ve IP'sine göre tek çağrıda puanlar; kayıt formu gönderildiğinde arka ucunuzdan çağrılır (tarayıcıda hesaplanan bir karar sahte olabilir). { "email": "...", "ip": "...", "userAgent": "..." } gönderin — userAgent isteğe bağlıdır. Yanıt; tam e-posta kontrolü sonucunu (email), IP'nin ülkesini ve ASN'sini ve — güvenlik verisi içeren planlarda — VPN/Tor/veri merkezi/tehdit göstergelerini (ip), e-posta alan adının herkese açık kayıt (RDAP) verilerine göre gün cinsinden yaşını (emailDomainAgeDays; bilinmediğinde ve tanınmış bireysel sağlayıcılar için null), 0–100 arası bir puanı (aşağıdaki gerekçe ağırlıklarının toplamı, en fazla 100) ve bir kararı içerir: 60 ve üzeri reject, 25 ve üzeri review, aksi halde accept. Güvenlik verisi olmayan bir planda ip.security null olur, puan yalnızca e-posta sinyallerini kullanır ve reasons ip_security_unavailable içerir. Bir istek sayılır. Yalnızca gizli anahtar.

curl https://api.watch-ip.com/v1/signup/check \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@new-startup.io", "ip": "203.0.113.1"}'

{
  "email": { "email": "jane@new-startup.io", "verdict": "accept", "reasons": [], ... },
  "ip": {
    "ip": "203.0.113.1",
    "country": "US",
    "asn": 64500,
    "asOrganization": "Example Hosting",
    "security": { "isTor": false, "isVpn": false, "isDatacenter": true, "isThreat": false, "isSanctionedNetwork": false }
  },
  "emailDomainAgeDays": 12,
  "score": 45,
  "verdict": "review",
  "reasons": ["new_domain", "ip_datacenter"]
}

Sınırlar

Kontrol edilen her adres, planınızın paylaşılan aylık kotasından bir istek olarak düşülür — tekli kontrol, toplu istekteki her adres, liste işindeki farklı her adres — ve bir kayıt kontrolü bir istektir. Toplu istekler ve liste işleri bütünüyle kabul edilir veya reddedilir, asla kısmen yerine getirilmez. Dakika başına hız sınırı öğeleri değil HTTP çağrılarını sayar: en fazla 100 IP veya e-posta adresi içeren bir toplu istek tek bir istek sayılır; her öğe ise aylık istek kotasına yine ayrı ayrı sayılır. Liste işi yüklemeleri ve sonuçları, iş oluşturulduktan 7 gün sonra silinir. DNS sorgularının kısa bir zaman bütçesi vardır: biri başarısız olduğunda veya zaman aşımına uğradığında sonuç, hata yerine mx.status unknown ve dns_unavailable gerekçesine düşer. Tek kullanımlık alan adı verileri, topluluk tarafından sürdürülen üç açık kaynaklı listeden birleştirilir, birkaç saatte bir yenilenir ve listelenen alan adlarına hizmet verdiği gözlemlenen posta sunucularıyla genişletilir — veri kaynaklarına bakın. Çok yeni bir tek kullanımlık sağlayıcı henüz işaretlenmemiş olabilir. Tüm kontroller alan adı ve adres düzeyindedir: hiçbir posta kutusuyla iletişim kurulmaz, dolayısıyla hiçbir sonuç bir posta kutusunun var olduğunu, kime ait olduğunu veya postanın oraya ulaşacağını kanıtlamaz.