API Validasi Email Real-Time: Panduan Developer

Validasi email waktu nyata memeriksa sebuah alamat saat pengguna masih berada di formulir Anda. Proses ini berjalan dalam beberapa ratus milidetik antara "Kirim" dan layar berikutnya, lalu menjawab satu pertanyaan: apakah alamat ini boleh masuk ke database Anda? API validasi email waktu nyata mengambil keputusan itu untuk Anda. API ini memeriksa sintaks, domain dan catatan MX-nya, sinyal alamat sekali pakai dan peran, perilaku catch-all, serta—bila Anda memintanya—kotak surat itu sendiri. Kemudian, API ini mengembalikan hasil terstruktur yang dapat ditindaklanjuti oleh kode Anda.

Panduan ini ditujukan bagi pengembang yang menambahkan penyaring tersebut ke formulir pendaftaran, checkout, atau prospek. Panduan ini membahas fungsi pemeriksaan, cara memanggil API, cara mengubah setiap status menjadi keputusan produk, dan cara tetap cepat ketika server email lambat. Contoh-contohnya menggunakan API validasi email BillionVerify, tetapi saran desainnya berlaku untuk penyedia mana pun.

Apa Itu Validasi Email Real-Time?

Validasi email real-time adalah pemeriksaan yang berjalan saat alamat dimasukkan, bukan berhari-hari kemudian ketika kampanye dikirim. Pengguna mengetikkan alamat. Frontend atau backend Anda mengirimkannya ke API pemeriksa email. API menjawab dengan status seperti valid, invalid, atau catchall, beserta sinyal yang mendasarinya. Aplikasi Anda kemudian mengizinkan pendaftaran, memblokirnya, atau meminta pengguna memperbaiki salah ketik.

Intinya adalah waktu. Salah ketik seperti gmial.com tidak membutuhkan biaya untuk diperbaiki saat pengguna masih berada di formulir. Setelah email sambutan mengalami bounce, salah ketik yang sama membuat Anda kehilangan pelanggan. Alamat yang buruk juga merusak reputasi pengirim Anda, karena setiap hard bounce memberi tahu penyedia mailbox bahwa Anda mengirim ke alamat yang belum dikonfirmasi. Verifikasi email real-time menghentikannya sejak awal.

Ini juga membantu melawan penipuan: pemeriksaan real-time dapat menandai inbox sekali pakai sebelum akun dibuat.

Validasi Email Real-Time vs Massal

Kedua pendekatan menggunakan pemeriksaan yang sama. Perbedaannya terletak pada kapan pemeriksaan dijalankan dan berapa banyak waktu yang tersedia.

• Validasi real-time berjalan pada satu alamat setiap kali, di dalam permintaan pengguna. Proses ini memiliki batas waktu yang ketat, sering kali jauh di bawah satu detik, karena formulir yang lambat akan kehilangan pendaftar. Proses ini mencegah data buruk masuk.
• Validasi massal berjalan pada seluruh daftar, di latar belakang. Proses ini dapat memakan waktu beberapa menit atau jam, dan tidak ada yang menunggu di layar. Proses ini membersihkan data yang sudah ada di sistem Anda, misalnya sebelum kampanye besar atau setelah impor CRM.

Sebagian besar tim membutuhkan keduanya. Pemeriksaan real-time menjaga data baru tetap bersih, sementara proses verifikasi massal berkala menangkap alamat yang menjadi tidak valid seiring waktu, seperti karyawan yang telah meninggalkan perusahaan. Untuk perbandingan yang lebih mendalam, lihat validasi email real-time vs massal.

Apa yang Sebenarnya Diuji oleh Pemeriksaan Real-Time

API validasi email menjalankan serangkaian pemeriksaan, dari yang murah hingga yang mahal. Masing-masing menyingkirkan jenis alamat yang buruk.

Sintaks

Pemeriksaan pertama adalah format. Apakah terdapat tepat satu @? Apakah bagian lokal terdiri dari karakter yang diizinkan? Apakah domain tersebut tampak seperti domain? Sintaks menolak data yang jelas tidak valid, seperti john@@example atau jane.example.com. Pemeriksaan ini cepat dan tidak memerlukan panggilan jaringan. Namun, sintaks yang sempurna tidak memberi tahu apakah kotak surat tersebut benar-benar ada.

Catatan domain dan MX

Selanjutnya, API mencari domain tersebut di DNS. Domain tanpa catatan MX tidak dapat menerima email, sehingga alamat di sana tidak berguna sebersih apa pun tampilannya. Ini mendeteksi domain yang salah eja dan domain perusahaan yang sudah tidak aktif. BillionVerify mengembalikan host MX yang ditemukan di mx_records, dan domain_suggestion dapat berisi koreksi yang mungkin ketika domain tersebut tampak seperti salah ketik dari domain umum.

Sinyal disposable, role, dan penyedia gratis

Beberapa alamat memang ada, tetapi tetap kurang cocok untuk produk Anda:

• Alamat disposable berasal dari layanan kotak masuk sementara dan biasanya berhenti berfungsi dalam hitungan jam. Lihat cara kerja deteksi email disposable.
• Alamat role seperti info@ atau support@ ditujukan kepada sebuah tim, bukan seseorang. Biasanya alamat ini dapat menerima email, tetapi cenderung lebih jarang berinteraksi.
• Alamat dari penyedia gratis seperti Gmail adalah hal normal bagi konsumen, tetapi layak dicatat pada formulir B2B.

API melaporkan hal-hal ini sebagai flag (is_disposable, is_role, is_free) sehingga Anda dapat memutuskan berdasarkan produk.

Domain catch-all

Beberapa server email menerima email untuk alamat apa pun di domainnya, baik alamat tersebut nyata maupun tidak. Untuk domain catch-all ini, pemeriksaan kotak surat tidak dapat membuktikan bahwa kotak masuk tertentu benar-benar ada. Hasil catch-all bukanlah hasil yang buruk. Ini berarti tingkat kepastiannya lebih rendah, sehingga skor lebih penting daripada labelnya. Deteksi email catch-all menjelaskan cara kerjanya dan alasan hal ini penting.

Pemeriksaan kotak surat SMTP

Pemeriksaan terdalam menanyakan server email penerima melalui SMTP apakah kotak surat tersebut akan menerima pesan, tanpa mengirimkannya. Pemeriksaan ini menemukan alamat pada domain nyata yang sudah tidak ada, seperti kotak masuk milik mantan karyawan. Ini juga merupakan langkah paling lambat karena bergantung pada server milik pihak lain. Di BillionVerify, pemeriksaan ini dikendalikan oleh parameter check_smtp. Jika Anda tidak menyertakannya, API akan menjalankan pemeriksaan SMTP; kirim check_smtp: false untuk melewatinya.

Reputasi domain

BillionVerify juga dapat mengembalikan objek domain_reputation dengan hasil blacklist untuk IP server email domain tersebut. Informasi ini hanya untuk referensi: tidak mengubah status, skor, atau biaya.

Cara Memanggil API Validasi Email Real-Time

Dengan BillionVerify, satu pemeriksaan real-time adalah satu permintaan HTTPS. URL dasar adalah https://api.billionverify.com/v1, dan kunci API Anda ditempatkan di header BV-API-KEY. Simpan kunci tersebut di server Anda. Jangan pernah menyertakannya dalam kode browser.

Berikut permintaan minimal, berdasarkan referensi API:

curl -X POST https://api.billionverify.com/v1/verify/single \
  -H "BV-API-KEY: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","check_smtp":true}'

Permintaan ini menerima tiga parameter:

Respons yang berhasil membungkus hasil dalam envelope standar. Berikut contoh singkat untuk alamat yang dapat menerima email:

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "email": "user@example.com",
    "status": "valid",
    "score": 0.95,
    "is_deliverable": true,
    "is_disposable": false,
    "is_catchall": false,
    "is_role": false,
    "is_free": false,
    "domain": "example.com",
    "mx_records": ["mail.example.com"],
    "check_smtp": true,
    "reason": "smtp_deliverable",
    "domain_suggestion": "",
    "response_time": 250,
    "credits_used": 1
  }
}

Jika Anda lebih memilih SDK, BillionVerify menyediakan SDK resmi untuk Node.js, Python, TypeScript, Go, PHP, dan Java. Di Node.js, npm install billionverify-sdk memberi Anda klien dengan metode verify; di Python, paketnya adalah billionverify.

Membaca Respons: Status, Skor, dan Alasan

Kolom status adalah dasar sebagian besar percabangan kode. Berikut arti setiap status dan default yang masuk akal untuk formulir pendaftaran:

score memberi sinyal yang lebih terperinci antara 0 dan 1. Sebagai panduan umum, hasil valid mendapat skor 0.85 hingga 1.0, catchall sekitar 0.55 hingga 0.75, unknown 0.3 hingga 0.6, disposable 0.1, dan invalid 0. Hasil role mempertahankan skor dari pemeriksaan yang mendasarinya. Anda dapat menggunakan skor ini untuk menetapkan ambang batas sendiri bagi kasus yang berada di batas, misalnya hanya menerima alamat catch-all di atas skor tertentu pada formulir bernilai tinggi.

Kolom reason menjelaskan hasil pemeriksaan. Hasil invalid mungkin disertai invalid_syntax, no_mx_records, atau mailbox_not_found, dan masing-masing mengarah pada pesan yang berbeda bagi pengguna. Masalah sintaks berarti “periksa formatnya”. Kotak surat yang tidak ditemukan berarti “kotak masuk ini tidak ada”. Halaman alasan verifikasi mencantumkan setiap alasan dan menjelaskan alasan unknown mana yang layak dicoba lagi.

Dua kolom membantu pengguna secara langsung: domain_suggestion dapat digunakan untuk menampilkan petunjuk “Apakah maksud Anda gmail.com?”, sedangkan is_disposable menjelaskan mengapa alamat sekali pakai ditolak.

Merancang Alur Pendaftaran Berdasarkan Anggaran Latensi

Bagian tersulit adalah memasukkan pemeriksaan ke dalam formulir tanpa memperlambatnya. Mulailah dengan menetapkan anggaran. Tentukan berapa lama Anda bersedia menahan pengguna, misalnya 300 hingga 500 milidetik saat mengirimkan formulir. Semua hal lainnya mengikuti angka tersebut.

Salinan produk BillionVerify menempatkan hasil cache di bawah 200 ms dan pemeriksaan SMTP lengkap pada rata-rata 1–3 detik. Perbedaan tersebut memberi Anda dua desain yang baik:

1. Pemeriksaan lengkap dengan batas waktu. Panggil API dengan SMTP aktif dan batas waktu 2–3 detik. Sebagian besar jawaban tiba tepat waktu dan memberi Anda hasil valid atau invalid yang jelas. Jika batas waktu tercapai, izinkan proses tetap berjalan dan lakukan pemeriksaan ulang nanti.
2. Pemeriksaan cepat sekarang, pemeriksaan mendalam nanti. Panggil API dengan check_smtp: false. Ini hanya menyelesaikan kasus-kasus yang jelas: sintaks yang salah, domain tanpa data MX, serta alamat sekali pakai dan alamat peran. Alamat pada domain yang berfungsi akan kembali sebagai unknown dengan alasan smtp_unverifiable, dan ini memang diharapkan. Terima alamat tersebut, lalu jalankan panggilan kedua dengan SMTP aktif dari pekerjaan latar belakang. Jika kotak surat tidak ada, tandai akun tersebut dan minta pengguna mengonfirmasi alamatnya.

Beberapa kebiasaan frontend juga membantu:

• Validasi saat blur atau submit, bukan pada setiap penekanan tombol. Memeriksa j, jo, joh membuang panggilan dan kredit.
• Jalankan pemeriksaan sintaks lokal terlebih dahulu untuk menghemat satu perjalanan bolak-balik pada kesalahan yang jelas.
• Panggil API dari backend Anda. Server Anda menyimpan API key dan mencatat hasilnya; browser hanya menampilkan hasilnya.

Untuk detail UX seperti susunan kata, penempatan kesalahan, dan kapan menampilkan petunjuk, lihat verifikasi email selama pendaftaran.

Gagal Terbuka atau Gagal Tertutup? Menangani Timeout dan Ketidakpastian

Pola yang cocok untuk sebagian besar produk adalah: gagal tertutup untuk kesalahan yang jelas, gagal terbuka untuk ketidakpastian.

• Gagal tertutup berarti Anda memblokir pendaftaran. Lakukan ini saat API menyatakan bahwa alamat tersebut jelas bermasalah: invalid dengan invalid_syntax atau no_mx_records, atau alamat disposable pada formulir yang akun sekali pakai dapat menimbulkan kerugian.
• Gagal terbuka berarti Anda mengizinkan pengguna masuk dan menindaklanjutinya nanti. Lakukan ini saat jawabannya tidak pasti: status unknown, domain catch-all, atau timeout Anda sendiri aktif sebelum API memberikan jawaban.

Mengapa tidak memblokir alamat yang tidak pasti juga? Banyak orang sungguhan berada di balik alamat-alamat tersebut. Server email perusahaan sering menerapkan greylisting atau membatasi laju pemeriksaan SMTP, sehingga memblokirnya dapat menghilangkan pendaftaran sungguhan. Terima, beri tag pada catatan tersebut, lalu periksa kembali nanti.

Tetapkan timeout sisi klien pada panggilan API yang sesuai dengan anggaran latensi Anda. Saat timeout aktif, perlakukan hasilnya sebagai unknown: terima, simpan tanda, dan masukkan pemeriksaan ulang ke antrean latar belakang. Coba lagi hasil unknown nanti, bukan di dalam permintaan.

Contoh: Memvalidasi Email saat Pendaftaran di Node.js

Sketsa di bawah menunjukkan pemeriksaan cepat (desain 2) dalam handler pendaftaran. Sketsa ini menggunakan endpoint REST dan kolom respons yang telah didokumentasikan, batas waktu, serta aturan fail open atau fail closed di atas. Sesuaikan nama-namanya dengan framework Anda.

const BLOCK = new Set(['invalid', 'disposable']);

async function checkEmail(email) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 400);

  try {
    const response = await fetch('https://api.billionverify.com/v1/verify/single', {
      method: 'POST',
      headers: {
        'BV-API-KEY': process.env.BV_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ email, check_smtp: false }),
      signal: controller.signal,
    });
    const body = await response.json();
    if (!body.success) return { allow: true, recheck: true };

    const { status, reason, domain_suggestion } = body.data;
    if (BLOCK.has(status)) {
      return { allow: false, reason, suggestion: domain_suggestion };
    }
    return { allow: true, recheck: status === 'unknown' || status === 'catchall' };
  } catch {
    // Timeout or network error: fail open and re-check in the background.
    return { allow: true, recheck: true };
  } finally {
    clearTimeout(timer);
  }
}

Tanpa SMTP, sebagian besar alamat nyata akan berstatus unknown dan mendapatkan flag recheck. Setelah akun disimpan, pekerjaan latar belakang memanggil endpoint yang sama dengan SMTP aktif untuk setiap data yang ditandai recheck. Tutorial Node.js menjelaskan penyiapan yang lebih lengkap, termasuk SDK resmi. Permintaan yang sama dapat digunakan dari Python atau bahasa apa pun yang memiliki klien HTTP.

Batas Laju, Caching, dan Biaya

Pemeriksaan real-time berada di jalur pendaftaran Anda, jadi batasnya menjadi batas Anda. Rencanakan hal itu.

Batas laju. BillionVerify melindungi kapasitasnya dengan batas per akun. Saat Anda mencapainya, API mengembalikan HTTP 429 dengan kode 1003 dan header Retry-After. Kurangi laju dan coba lagi, serta pertahankan aturan fail-open Anda sendiri agar batas tidak pernah memblokir pengguna yang sebenarnya.

Caching. Hasil disimpan dalam cache, sehingga pemeriksaan berulang berlangsung cepat. Memeriksa ulang alamat yang telah diverifikasi akun Anda dalam 24 jam terakhir tidak dikenai biaya. Gunakan force_refresh: true hanya saat Anda benar-benar memerlukan jawaban terbaru, karena tindakan ini melewati cache dan ditagihkan seperti pemeriksaan baru.

Biaya. Satu pemeriksaan biasanya menggunakan 1 kredit, yang ditampilkan dalam credits_used. Setiap hasil unknown gratis, begitu juga kegagalan sintaks. Validasi saat pengiriman, bukan pada setiap penekanan tombol, dan jangan memeriksa ulang alamat yang baru saja Anda verifikasi. BillionVerify memberikan 20 kredit gratis setiap hari Anda masuk, hingga 600 per bulan, yang cukup untuk membangun dan menguji integrasi. Paket kredit berbayar tercantum di halaman harga.

Melampaui Formulir: Batch, File, dan Webhook

Validasi real-time mencakup alamat baru satu per satu. Untuk kebutuhan lainnya, API yang sama memiliki titik akses lain:

• Batch kecil. POST /verify/bulk memeriksa hingga 50 alamat dalam satu permintaan, cocok untuk sinkronisasi CRM atau layar impor.
• Daftar besar. POST /verify/file menerima file CSV, TXT, atau XLSX dan memprosesnya di latar belakang.
• Webhook. Daripada melakukan polling pada tugas file, daftarkan webhook untuk event file.completed dan file.failed. Lihat panduan webhook verifikasi email untuk pemeriksaan tanda tangan dan percobaan ulang.
• Pemeriksaan alamat sekali pakai saja. POST /verify/disposable hanya menjawab pertanyaan tentang alamat sekali pakai dan tidak menggunakan kredit.

Pengaturan yang umum: pemeriksaan real-time pada setiap formulir, batch setiap malam untuk catatan yang ditandai recheck, dan tugas file sebelum kampanye besar.

Daftar Periksa Validasi Email Real-Time

Sebelum merilis, periksa daftar ini:

• API key berada di server, tidak pernah di browser.
• Sintaks diperiksa secara lokal sebelum panggilan API.
• Jalur permintaan menggunakan check_smtp: false dan batas waktu yang sesuai dengan anggaran latensi Anda.
• invalid dan disposable memiliki pesan kesalahan yang jelas dan spesifik.
• unknown, catchall, dan batas waktu dianggap berhasil sementara, lalu dimasukkan ke antrean untuk diperiksa ulang.
• domain_suggestion digunakan untuk memberikan petunjuk kesalahan ketik.
• Respons 429 melakukan backoff tanpa memblokir pengguna.
• Hasil disimpan bersama data pengguna, sehingga Anda dapat mengukur tingkat bounce nanti.

FAQ

Apa itu API validasi email secara real-time?

API validasi email secara real-time memeriksa satu alamat email saat pengguna mengirimkan formulir dan mengembalikan hasil dalam waktu kurang dari satu detik. API ini menjalankan pemeriksaan sintaks, domain, MX, sekali pakai, peran, dan catch-all, serta pemeriksaan kotak surat SMTP secara opsional, sehingga aplikasi Anda dapat menerima, memblokir, atau menandai alamat tersebut sebelum masuk ke database.

Apa perbedaan validasi email secara real-time dan validasi massal?

Validasi email secara real-time memeriksa satu alamat setiap kali dalam satu permintaan pengguna dan harus memberikan jawaban dengan cepat. Validasi massal memeriksa seluruh daftar di latar belakang dan dapat memerlukan waktu lebih lama. Gunakan pemeriksaan real-time untuk menjaga data baru tetap bersih dan pemeriksaan massal untuk membersihkan data yang sudah Anda miliki.

Haruskah saya menjalankan pemeriksaan SMTP pada setiap pendaftaran?

Tergantung pada batas latensi Anda. Pemeriksaan SMTP mengonfirmasi keberadaan kotak surat, jadi tanpa pemeriksaan ini, sebagian besar alamat nyata akan menghasilkan unknown. Jika Anda dapat menunggu 2–3 detik, jalankan pemeriksaan saat formulir dikirim dengan batas waktu. Jika tidak, jalankan pemeriksaan cepat dengan check_smtp: false dan lakukan pemeriksaan SMTP dalam tugas latar belakang.

Apa yang harus saya lakukan dengan hasil catch-all dan unknown?

Terima dan periksa kembali nanti. Domain catch-all menerima setiap alamat, sehingga pemeriksaan kotak surat tidak dapat membuktikan bahwa kotak masuk tersebut ada, sementara hasil unknown berarti pemeriksaan tidak dapat diselesaikan. Memblokir pengguna ini akan kehilangan pendaftaran yang valid; menandai dan memeriksanya kembali menjaga data Anda tetap bersih tanpa mengurangi konversi.

Bisakah saya memanggil API pemeriksa email dari browser?

Tidak. Hal itu akan mengekspos API key Anda. Panggil API dari backend dan kembalikan hanya keputusannya.

Seberapa cepat verifikasi email secara real-time?

Dengan BillionVerify, hasil yang tersimpan dalam cache dikembalikan dalam waktu kurang dari 200 ms, sedangkan pemeriksaan SMTP lengkap memerlukan rata-rata 1–3 detik. Karena itu, pemeriksaan cepat tanpa SMTP sebaiknya berada dalam jalur permintaan, sedangkan pemeriksaan SMTP dilakukan di latar belakang.

Berapa biaya API validasi email?

Di BillionVerify, satu pemeriksaan biasanya menggunakan 1 kredit, dan setiap hasil unknown gratis. Anda mendapatkan 20 kredit gratis setiap hari saat masuk, hingga 600 kredit per bulan, sementara paket kredit berbayar tersedia di halaman harga. force_refresh melewati cache dan ditagihkan seperti pemeriksaan baru.

Mulai Memvalidasi Email Secara Waktu Nyata

Validasi email waktu nyata berarti lebih sedikit email terpental, lebih sedikit akun palsu, dan lebih sedikit pengguna yang hilang karena salah ketik. Tempatkan pemeriksaan cepat di jalur permintaan, pindahkan pemeriksaan lambat ke latar belakang, dan biarkan kegagalan yang jelas memblokir sementara hasil yang tidak pasti tetap diteruskan. Buat akun BillionVerify gratis, dapatkan kunci API, dan lakukan panggilan API validasi email pertama Anda dari dokumentasi di atas.