Referensi API Pemeriksaan Email

Autentikasi

POST /v1/email/validate menerima publishable key yang dikunci origin melalui header X-Api-Key — jenis key dan model allowed-origins yang sama dengan GET /v1/geo. Semua endpoint lain di halaman ini (batch, list job, pemeriksaan pendaftaran) menerima banyak alamat atau IP sembarang, sehingga memerlukan secret key Anda melalui Authorization: Bearer dan hanya boleh dipanggil dari backend Anda; publishable key akan mendapat 403 di sana.

Contoh

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

Verdict dan kode alasan

Setiap kondisi menetapkan verdict minimum; yang paling berat menang, dan reasons mencantumkan semuanya, dari yang paling berat. Apakah alamat dari penyedia gratis dapat diterima, Anda yang menentukan — hal itu tidak pernah mengubah verdict.

Pemeriksaan batch

POST/v1/email/batch

Memeriksa 1–100 alamat dalam satu request dengan pemeriksaan dan bentuk hasil yang sama dengan POST /v1/email/validate, satu hasil per alamat sesuai urutan input. Kirim { "emails": [...] }. Alamat pada domain yang sama berbagi satu pencarian DNS. Dihitung satu request per alamat terhadap batas bulanan paket Anda; batch yang akan melampaui batas ditolak seluruhnya dengan 429 monthly_limit_exceeded. Untuk rate limit per menit, seluruh panggilan dihitung sebagai satu request. Hanya secret key.

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"], ... }
  ]
}

List job email

POST/v1/email/jobs

Memeriksa hingga 100.000 alamat di latar belakang. Kirim JSON { "emails": [...], "filename": "..." } atau isi text/csv berukuran maksimal 10 MB: kolom berjudul email (juga e-mail, email address, email_address, atau mail, tanpa membedakan huruf besar-kecil) yang digunakan, atau kolom pertama jika tidak ada judul yang menyebutkannya; pemisah koma, titik koma, dan tab dideteksi otomatis. Biaya job dikenakan saat dibuat — satu request per alamat unik (kecocokan persis), sehingga duplikat tetap diperiksa tetapi dikenakan biaya sekali — dan daftar yang akan melampaui batas bulanan Anda ditolak seluruhnya. Jika sebagian job tidak dapat diproses setelah beberapa kali percobaan ulang, job ditandai failed dan kredit untuk bagian yang tidak diproses dikembalikan. Merespons 202 dengan objek job. Hanya secret key; job yang sama juga dapat diunggah dan diunduh dari halaman Email lists di dasbor.

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

Status job

GET/v1/email/jobs/{id}

Mengembalikan objek job yang sama. Lakukan polling hingga status bernilai completed; polling tidak dikenakan biaya.

Hasil job

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

Mengunduh CSV dengan satu baris untuk setiap baris yang dikirim, sesuai urutan pengiriman — termasuk duplikat. Kolom: 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 dipisahkan titik koma, sel kosong berarti null, dan mx_status kosong untuk alamat yang tidak valid secara sintaks (tidak ada yang dicari). Alamat tidak valid yang diawali =, +, - atau @ diberi awalan apostrof agar aplikasi spreadsheet tidak menjalankannya sebagai rumus. 409 sampai job selesai, 410 setelah kedaluwarsa. Pengunduhan tidak dikenakan biaya.

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

Pemeriksaan pendaftaran

POST/v1/signup/check

Memberi skor pendaftaran dari alamat email dan IP-nya dalam satu panggilan, dari backend Anda saat formulir pendaftaran dikirim (verdict yang dihitung di browser dapat dipalsukan). Kirim { "email": "...", "ip": "...", "userAgent": "..." } — userAgent bersifat opsional. Respons berisi hasil pemeriksaan email lengkap (email), negara dan ASN dari IP serta — pada paket yang menyertakan data keamanan — indikator VPN/Tor/pusat data/ancamannya (ip), usia domain email dalam hari dari data registrasi publik (RDAP) (emailDomainAgeDays, null jika tidak diketahui dan untuk penyedia konsumen terkenal), skor 0–100 (jumlah bobot alasan di bawah, maksimum 100), dan verdict: reject pada 60 atau lebih, review pada 25 atau lebih, selain itu accept. Pada paket tanpa data keamanan, ip.security bernilai null, skor hanya menggunakan sinyal email, dan reasons menyertakan ip_security_unavailable. Dihitung sebagai satu request. Hanya secret key.

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

Batas

Setiap alamat yang diperiksa dihitung sebagai satu request terhadap batas bulanan bersama paket Anda — pemeriksaan tunggal, setiap alamat dalam batch, setiap alamat unik dalam list job — dan pemeriksaan pendaftaran adalah satu request. Batch dan list job diterima atau ditolak seluruhnya, tidak pernah dipenuhi sebagian. Rate limit per menit menghitung panggilan HTTP, bukan item: satu batch berisi hingga 100 IP atau alamat email dihitung sebagai satu request, sementara setiap item tetap dihitung terpisah terhadap batas request bulanan. Unggahan dan hasil list job dihapus 7 hari setelah job dibuat. Pencarian DNS memiliki anggaran waktu yang singkat: jika salah satunya gagal atau timeout, hasilnya turun menjadi mx.status unknown dan alasan dns_unavailable, bukan error. Data domain sekali pakai digabungkan dari tiga daftar open source yang dikelola komunitas, diperbarui setiap beberapa jam, dan diperluas dengan server email yang teramati melayani domain yang terdaftar — lihat sumber data. Penyedia sekali pakai yang sangat baru mungkin belum ditandai. Semua pemeriksaan dilakukan di tingkat domain dan alamat: tidak ada mailbox yang dihubungi, sehingga tidak ada hasil yang memastikan bahwa mailbox ada, siapa pemiliknya, atau bahwa email ke alamat tersebut akan sampai.