API Pengesahan E-mel Masa Nyata: Panduan Pembangun

Pengesahan e-mel masa nyata menyemak alamat ketika pengguna masih berada dalam borang anda. Ia berjalan dalam beberapa ratus milisaat antara "Submit" dan skrin seterusnya, serta menjawab satu soalan: patutkah alamat ini dimasukkan ke dalam pangkalan data anda? API pengesahan e-mel masa nyata membuat keputusan itu untuk anda. Ia memeriksa sintaks, domain dan rekod MX, isyarat alamat pakai buang dan peranan, tingkah laku catch-all dan, apabila anda memintanya, peti mel itu sendiri. Kemudian ia mengembalikan hasil berstruktur yang boleh diambil tindakan oleh kod anda.

Panduan ini ditujukan kepada pembangun yang menambahkan penapis itu pada borang pendaftaran, pembayaran atau prospek. Ia menerangkan fungsi semakan tersebut, cara memanggil API, cara menukar setiap status kepada keputusan produk dan cara mengekalkan kelajuan apabila pelayan mel lambat. Contoh-contoh menggunakan API pengesahan e-mel BillionVerify, tetapi nasihat reka bentuk ini terpakai kepada mana-mana pembekal.

Apakah Pengesahan E-mel Masa Nyata?

Pengesahan e-mel masa nyata ialah pemeriksaan yang dijalankan ketika alamat dimasukkan, bukannya beberapa hari kemudian apabila kempen dihantar. Pengguna menaip alamat. Bahagian hadapan atau bahagian belakang aplikasi anda menghantarnya kepada API pemeriksa e-mel. API tersebut menjawab dengan status seperti valid, invalid atau catchall, bersama isyarat yang mendasarinya. Aplikasi anda kemudian membenarkan pendaftaran, menyekatnya atau meminta pengguna membetulkan kesilapan taip.

Intinya ialah masa. Kesilapan taip seperti gmial.com tidak memerlukan kos untuk dibetulkan ketika pengguna masih mengisi borang. Selepas e-mel alu-aluan gagal dihantar, kesilapan taip yang sama menyebabkan anda kehilangan pelanggan. Alamat yang tidak sah juga menjejaskan reputasi penghantar anda kerana setiap kegagalan penghantaran kekal memberitahu penyedia peti mel bahawa anda menghantar kepada alamat yang belum disahkan. Pengesahan e-mel masa nyata menghalangnya sejak awal.

Ia juga membantu mencegah penipuan: pemeriksaan masa nyata boleh menandakan peti masuk pakai buang sebelum akaun diwujudkan.

Pengesahan E-mel Masa Nyata vs Pukal

Kedua-dua pendekatan menggunakan pemeriksaan yang sama. Perbezaannya ialah bila pemeriksaan dijalankan dan berapa banyak masa yang tersedia.

• Pengesahan masa nyata dijalankan pada satu alamat pada satu-satu masa, dalam permintaan pengguna. Ia mempunyai had masa yang ketat, selalunya jauh di bawah satu saat, kerana borang yang lambat akan menyebabkan pendaftaran berkurang. Ia menghalang data tidak sah daripada masuk.
• Pengesahan pukal dijalankan pada keseluruhan senarai, di latar belakang. Ia boleh mengambil masa beberapa minit atau jam, dan tiada sesiapa menunggu di hadapan skrin. Ia membersihkan data yang sudah ada dalam sistem anda, contohnya sebelum kempen besar atau selepas import CRM.

Kebanyakan pasukan memerlukan kedua-duanya. Pemeriksaan masa nyata memastikan data baharu kekal bersih, manakala proses pengesahan pukal berkala mengesan alamat yang menjadi tidak sah dari semasa ke semasa, seperti alamat pekerja yang telah meninggalkan syarikat. Untuk perbandingan yang lebih mendalam, lihat pengesahan e-mel masa nyata vs pukal.

Perkara yang Sebenarnya Diuji oleh Semakan Masa Nyata

API pengesahan email menjalankan beberapa semakan, daripada yang murah hingga yang mahal. Setiap semakan menolak jenis alamat buruk yang berbeza.

Sintaks

Semakan pertama ialah format. Adakah terdapat tepat satu @? Adakah bahagian setempat terdiri daripada aksara yang dibenarkan? Adakah domain itu kelihatan seperti domain? Sintaks menolak data jelas tidak sah, seperti john@@example atau jane.example.com. Ia pantas dan tidak memerlukan panggilan rangkaian. Namun, sintaks yang sempurna tidak membuktikan bahawa peti mel itu wujud.

Rekod domain dan MX

Seterusnya, API mencari domain tersebut dalam DNS. Domain tanpa rekod MX tidak boleh menerima email, jadi alamat di situ tidak berguna walaupun kelihatan kemas. Ini mengesan domain yang tersalah eja dan domain syarikat yang sudah tidak aktif. BillionVerify mengembalikan hos MX yang ditemuinya dalam mx_records, dan domain_suggestion boleh mengandungi pembetulan yang berkemungkinan apabila domain itu kelihatan seperti salah eja bagi domain lazim.

Isyarat alamat pakai buang, peranan dan penyedia percuma

Sesetengah alamat wujud tetapi masih kurang sesuai untuk produk anda:

• Alamat pakai buang berasal daripada perkhidmatan peti masuk sementara dan biasanya berhenti berfungsi dalam masa beberapa jam. Lihat cara pengesanan email pakai buang berfungsi.
• Alamat peranan seperti info@ atau support@ ditujukan kepada pasukan, bukan individu. Biasanya alamat ini boleh dihantar, tetapi cenderung kurang berinteraksi.
• Alamat penyedia percuma seperti Gmail adalah perkara biasa bagi pengguna, tetapi wajar direkodkan pada borang B2B.

API melaporkan perkara ini sebagai bendera (is_disposable, is_role, is_free) supaya anda boleh membuat keputusan mengikut produk.

Domain tangkap semua

Sesetengah pelayan email menerima email untuk sebarang alamat dalam domain mereka, sama ada alamat itu wujud atau tidak. Bagi domain tangkap semua ini, semakan peti mel tidak dapat membuktikan bahawa peti masuk tertentu wujud. Keputusan tangkap semua bukanlah keputusan yang buruk. Ini bermakna tahap kepastian lebih rendah, jadi skor lebih penting daripada label. Pengesanan email tangkap semua menerangkan cara perkara ini berfungsi dan sebabnya penting.

Semakan peti mel SMTP

Semakan paling mendalam bertanya kepada pelayan email penerima melalui SMTP sama ada peti mel tersebut akan menerima mesej, tanpa menghantar mesej. Ia mengesan alamat pada domain sebenar yang sudah tidak wujud, seperti peti masuk bekas pekerja. Ini juga langkah paling perlahan kerana ia bergantung pada pelayan milik pihak lain. Dalam BillionVerify, ia dikawal oleh parameter check_smtp. Jika anda tidak menyertakannya, API menjalankan semakan SMTP; hantar check_smtp: false untuk melangkaunya.

Reputasi domain

BillionVerify juga boleh mengembalikan objek domain_reputation dengan keputusan senarai hitam bagi IP pelayan email domain tersebut. Ia hanya untuk maklumat: ia tidak mengubah status, skor atau kos.

Cara Memanggil API Pengesahan Email Masa Nyata

Dengan BillionVerify, satu semakan masa nyata ialah satu permintaan HTTPS. URL asas ialah https://api.billionverify.com/v1, dan kunci API anda diletakkan dalam pengepala BV-API-KEY. Simpan kunci itu pada pelayan anda. Jangan sekali-kali memasukkannya dalam kod pelayar.

Berikut ialah permintaan minimum, berdasarkan rujukan 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 mengambil tiga parameter:

Respons yang berjaya membungkus hasil dalam sampul standard. Berikut ialah contoh ringkas untuk alamat yang boleh dihantar:

{
  "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 suka SDK, BillionVerify menyediakan SDK rasmi untuk Node.js, Python, TypeScript, Go, PHP dan Java. Dalam Node.js, npm install billionverify-sdk memberikan anda klien dengan kaedah verify; dalam Python, pakejnya ialah billionverify.

Membaca Respons: Status, Skor dan Sebab

Medan status ialah perkara yang paling kerap digunakan oleh cabang kod. Berikut ialah maksud setiap status dan tetapan lalai yang munasabah untuk borang pendaftaran:

score memberikan petunjuk yang lebih terperinci antara 0 hingga 1. Sebagai panduan kasar, 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 mengekalkan skor semakan asas. Anda boleh menggunakan skor untuk menetapkan ambang anda sendiri bagi kes sempadan, contohnya menerima alamat catch-all hanya jika melebihi skor tertentu pada borang bernilai tinggi.

Medan reason menerangkan keputusan tersebut. Hasil invalid mungkin disertai invalid_syntax, no_mx_records atau mailbox_not_found, dan setiap satunya menunjukkan mesej yang berbeza untuk pengguna. Masalah sintaks bermaksud "semak format". Peti mel yang tiada bermaksud "peti masuk ini tidak wujud". Halaman sebab pengesahan menyenaraikan setiap sebab dan menyatakan sebab unknown yang wajar dicuba semula.

Dua medan membantu pengguna secara langsung: domain_suggestion boleh mengaktifkan petunjuk "Adakah anda maksudkan gmail.com?", manakala is_disposable menerangkan sebab alamat sementara ditolak.

Mereka Bentuk Aliran Pendaftaran Berpandukan Bajet Kependaman

Bahagian yang sukar ialah memasukkan semakan ke dalam borang tanpa melambatkannya. Mulakan dengan menetapkan bajet. Tentukan berapa lama anda sanggup menahan pengguna, contohnya 300 hingga 500 milisaat semasa penghantaran. Segala-galanya bergantung pada angka itu.

Kandungan produk BillionVerify meletakkan hasil dicache di bawah 200 ms dan semakan SMTP penuh pada purata 1–3 saat. Perbezaan itu memberikan anda dua reka bentuk yang baik:

1. Semakan penuh dengan tamat masa. Panggil API dengan SMTP dihidupkan dan tamat masa selama 2–3 saat. Kebanyakan respons tiba tepat pada masanya dan memberikan anda keputusan valid atau invalid yang jelas. Jika tamat masa berlaku, benarkan permintaan diteruskan dan buat semakan semula kemudian.
2. Semakan pantas sekarang, semakan mendalam kemudian. Panggil API dengan check_smtp: false. Ini hanya menyelesaikan kes yang jelas: sintaks tidak sah, domain tanpa rekod MX, serta alamat pakai buang dan alamat peranan. Alamat pada domain yang berfungsi akan kembali sebagai unknown dengan sebab smtp_unverifiable, dan ini dijangka. Terima alamat tersebut, kemudian jalankan panggilan kedua dengan SMTP dihidupkan daripada tugas latar belakang. Jika peti mel itu tidak wujud, tandakan akaun tersebut dan minta pengguna mengesahkan alamat mereka.

Beberapa amalan frontend juga membantu:

• Sahkan semasa blur atau penghantaran, bukan pada setiap ketukan kekunci. Menyemak j, jo, joh membazirkan panggilan dan kredit.
• Jalankan semakan sintaks setempat terlebih dahulu untuk menjimatkan satu pusingan bagi kesilapan yang jelas.
• Panggil API daripada backend anda. Pelayan anda menyimpan kunci API dan merekodkan hasilnya; pelayar hanya memaparkan keputusan.

Untuk butiran UX seperti perkataan yang digunakan, peletakan ralat dan masa untuk memaparkan petunjuk, lihat pengesahan e-mel semasa pendaftaran.

Gagal Terbuka atau Gagal Tertutup? Mengendalikan Tamat Masa dan Perkara Tidak Diketahui

Corak yang sesuai untuk kebanyakan produk ialah: gagal tertutup apabila berlaku ralat jelas, gagal terbuka apabila terdapat ketidakpastian.

• Gagal tertutup bermaksud anda menyekat pendaftaran. Lakukan ini apabila API menyatakan alamat itu jelas tidak sah: invalid dengan invalid_syntax atau no_mx_records, atau alamat disposable pada borang yang akaun sementara boleh menyebabkan kemudaratan.
• Gagal terbuka bermaksud anda membenarkan pengguna meneruskan dan membuat susulan kemudian. Lakukan ini apabila jawapannya tidak pasti: status unknown, domain catch-all, atau tamat masa anda sendiri berlaku sebelum API memberikan jawapan.

Mengapa tidak menyekat alamat yang tidak pasti juga? Ramai orang sebenar berada di sebalik alamat tersebut. Pelayan mel korporat sering menggunakan greylist atau mengehadkan kadar pemeriksaan SMTP, jadi menyekatnya menyebabkan pendaftaran sebenar hilang. Terima, tandakan rekod itu, dan semak semula kemudian.

Tetapkan tamat masa pada sisi klien untuk panggilan API anda yang sepadan dengan bajet kependaman anda. Apabila tamat masa berlaku, anggap hasilnya sebagai unknown: terima, simpan tanda, dan masukkan semakan semula latar belakang ke dalam baris gilir. Cuba semula hasil unknown kemudian, bukan dalam permintaan yang sama.

Contoh: Mengesahkan E-mel Semasa Pendaftaran dalam Node.js

Gambaran di bawah menunjukkan pemeriksaan pantas (reka bentuk 2) dalam pengendali pendaftaran. Ia menggunakan titik akhir REST dan medan respons yang didokumenkan, tamat masa, serta peraturan gagal terbuka atau tertutup di atas. Sesuaikan nama mengikut rangka kerja 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, kebanyakan alamat sebenar akan kembali sebagai unknown dan menerima bendera recheck. Selepas akaun disimpan, tugas latar belakang memanggil titik akhir yang sama dengan SMTP diaktifkan untuk setiap rekod yang ditandakan sebagai recheck. Tutorial Node.js menerangkan persediaan yang lebih lengkap, termasuk SDK rasmi. Permintaan yang sama boleh digunakan daripada Python atau mana-mana bahasa dengan klien HTTP.

Had Kadar, Caching dan Kos

Semakan masa nyata berada dalam laluan pendaftaran anda, jadi hadnya menjadi had anda. Rancang untuknya.

Had kadar. BillionVerify melindungi kapasitinya dengan had bagi setiap akaun. Apabila anda mencapainya, API mengembalikan HTTP 429 dengan kod 1003 dan pengepala Retry-After. Kurangkan kadar dan cuba semula, serta kekalkan peraturan fail-open anda sendiri supaya had tidak pernah menyekat pengguna sebenar.

Caching. Keputusan dicache, sebab itulah semakan berulang kembali dengan pantas. Semakan semula alamat yang akaun anda sahkan dalam tempoh 24 jam terakhir adalah percuma. Gunakan force_refresh: true hanya apabila anda benar-benar memerlukan jawapan terkini, kerana ia melangkau cache dan dicaj seperti semakan baharu.

Kos. Satu semakan biasanya menggunakan 1 kredit, yang ditunjukkan dalam credits_used. Setiap keputusan unknown adalah percuma, begitu juga kegagalan sintaks. Sahkan semasa penghantaran dan bukannya pada setiap tekanan kekunci, dan jangan semak semula alamat yang baru-baru ini anda sahkan. BillionVerify memberikan 20 kredit percuma setiap hari anda log masuk, sehingga 600 sebulan, yang mencukupi untuk membina dan menguji integrasi. Pakej kredit berbayar disenaraikan di halaman harga.

Melangkaui Borang: Kelompok, Fail dan Webhook

Pengesahan masa nyata meliputi alamat baharu satu demi satu. Untuk keperluan lain, API yang sama menyediakan titik kemasukan lain:

• Kelompok kecil. POST /verify/bulk menyemak sehingga 50 alamat dalam satu permintaan, sesuai untuk penyegerakan CRM atau skrin import.
• Senarai besar. POST /verify/file menerima fail CSV, TXT atau XLSX dan memprosesnya di latar belakang.
• Webhook. Daripada meninjau kerja fail, daftarkan webhook untuk peristiwa file.completed dan file.failed. Lihat panduan webhook pengesahan e-mel untuk semakan tandatangan dan percubaan semula.
• Semakan khusus alamat boleh lupus. POST /verify/disposable hanya menjawab sama ada alamat itu boleh lupus dan tidak menggunakan kredit.

Persediaan biasa: semakan masa nyata pada setiap borang, kelompok setiap malam untuk rekod yang ditandai recheck, dan kerja fail sebelum kempen besar.

Senarai Semak Pengesahan E-mel Masa Nyata

Sebelum anda menerbitkannya, semak senarai ini:

• Kunci API berada di pelayan, bukan dalam pelayar.
• Sintaks disemak secara setempat sebelum panggilan API.
• Laluan permintaan menggunakan check_smtp: false dan tamat masa yang sesuai dengan bajet kependaman anda.
• invalid dan disposable mempunyai mesej ralat yang jelas dan khusus.
• unknown, catchall dan tamat masa gagal secara terbuka serta dimasukkan ke dalam baris gilir untuk semakan semula.
• domain_suggestion menggerakkan petunjuk kesilapan ejaan.
• Respons 429 berundur tanpa menyekat pengguna.
• Keputusan disimpan bersama rekod pengguna supaya anda boleh mengukur kadar lantunan kemudian.

Soalan Lazim

Apakah API pengesahan e-mel masa nyata?

API pengesahan e-mel masa nyata menyemak satu alamat e-mel apabila pengguna menghantar borang dan mengembalikan keputusan dalam masa kurang daripada sesaat. Ia menjalankan semakan sintaks, domain, MX, pakai buang, peranan dan catch-all, serta pilihan semakan peti mel SMTP, supaya aplikasi anda boleh menerima, menyekat atau menandakan alamat tersebut sebelum ia masuk ke pangkalan data anda.

Apakah perbezaan pengesahan e-mel masa nyata dengan pengesahan pukal?

Pengesahan e-mel masa nyata menyemak satu alamat pada satu-satu masa dalam permintaan pengguna dan mesti memberikan jawapan dengan pantas. Pengesahan pukal menyemak keseluruhan senarai di latar belakang dan boleh mengambil masa yang lebih lama. Gunakan semakan masa nyata untuk memastikan data baharu bersih, dan semakan pukal untuk membersihkan data yang sudah anda miliki.

Patutkah saya menjalankan semakan SMTP pada setiap pendaftaran?

Ia bergantung pada had kependaman anda. Semakan SMTP mengesahkan kewujudan peti mel, jadi tanpanya kebanyakan alamat sebenar akan kembali sebagai unknown. Jika anda boleh menunggu 2–3 saat, jalankan semakan itu semasa penghantaran dengan had masa. Jika tidak, jalankan semakan pantas dengan check_smtp: false dan lakukan semakan SMTP dalam tugas latar belakang.

Apakah yang patut saya lakukan dengan hasil catch-all dan unknown?

Terima hasil tersebut dan semak semula kemudian. Domain catch-all menerima setiap alamat, jadi semakan peti mel tidak dapat membuktikan bahawa peti masuk itu wujud, manakala hasil unknown bermaksud semakan tidak dapat diselesaikan. Menyekat pengguna ini akan menyebabkan pendaftaran sebenar hilang; menandakan dan menyemak semula mereka membantu memastikan data anda bersih tanpa menjejaskan kadar penukaran.

Bolehkah saya memanggil API pemeriksa e-mel daripada pelayar?

Tidak. Tindakan itu akan mendedahkan kunci API anda. Panggil API daripada backend anda dan kembalikan keputusannya sahaja.

Seberapa pantas pengesahan e-mel masa nyata?

Dengan BillionVerify, hasil cache dikembalikan dalam masa kurang daripada 200 ms, manakala semakan SMTP penuh mengambil masa purata 1–3 saat. Oleh itu, semakan pantas tanpa SMTP sesuai diletakkan dalam laluan permintaan, manakala semakan SMTP dijalankan di latar belakang.

Berapakah kos API pengesahan e-mel?

Dalam BillionVerify, satu semakan biasanya menggunakan 1 kredit, dan setiap hasil unknown adalah percuma. Anda menerima 20 kredit percuma setiap hari apabila log masuk, sehingga 600 sebulan, manakala pakej kredit berbayar tersedia di halaman harga. force_refresh melangkau cache dan dicaj seperti semakan baharu.

Mula Mengesahkan E-mel dalam Masa Nyata

Pengesahan e-mel masa nyata bermaksud kurang lantunan, kurang akaun palsu dan kurang pengguna yang hilang akibat kesilapan menaip. Letakkan semakan pantas dalam laluan permintaan, pindahkan semakan perlahan ke latar belakang, dan biarkan kegagalan yang jelas disekat manakala hasil yang tidak pasti diteruskan. Cipta akaun BillionVerify percuma, dapatkan kunci API dan buat panggilan API pengesahan e-mel pertama anda daripada dokumentasi di atas.