Walidacja adresu e-mail w czasie rzeczywistym sprawdza adres, gdy użytkownik nadal znajduje się w formularzu. Działa w ciągu kilkuset milisekund między kliknięciem „Prześlij” a wyświetleniem następnego ekranu i odpowiada na jedno pytanie: czy ten adres powinien trafić do Twojej bazy danych? API do walidacji adresów e-mail w czasie rzeczywistym podejmuje tę decyzję za Ciebie. Sprawdza składnię, domenę i jej rekordy MX, sygnały dotyczące adresów jednorazowych i ról, zachowanie typu catch-all oraz — jeśli o to poprosisz — samą skrzynkę pocztową. Następnie zwraca uporządkowany wynik, na podstawie którego Twój kod może podjąć działanie.
Ten przewodnik jest przeznaczony dla deweloperów, którzy dodają taki filtr do formularza rejestracji, finalizacji zakupu lub pozyskiwania leadów. Omawia działanie poszczególnych kontroli, sposób wywoływania API, przekształcanie każdego statusu w decyzję produktową oraz utrzymanie szybkości działania, gdy serwer pocztowy odpowiada wolno. Przykłady korzystają z API BillionVerify do walidacji adresów e-mail, ale zawarte tu zalecenia projektowe mają zastosowanie do każdego dostawcy.
Czym jest walidacja adresów e-mail w czasie rzeczywistym?
Walidacja adresu e-mail w czasie rzeczywistym to sprawdzenie wykonywane w momencie wpisywania adresu, a nie kilka dni później, gdy rozpoczyna się kampania. Użytkownik wpisuje adres. Twój frontend lub backend wysyła go do API sprawdzającego adresy e-mail. API odpowiada statusem takim jak valid, invalid lub catchall, wraz z sygnałami, które za nim stoją. Następnie aplikacja pozwala na rejestrację, blokuje ją lub prosi użytkownika o poprawienie literówki.
Liczy się czas. Literówkę, taką jak gmial.com, można bez żadnych kosztów poprawić, gdy użytkownik nadal znajduje się w formularzu. Gdy wiadomość powitalna zostanie odrzucona, ta sama literówka kosztuje Cię klienta. Błędne adresy szkodzą również reputacji nadawcy, ponieważ każde twarde odrzucenie informuje dostawców skrzynek pocztowych, że wysyłasz wiadomości na niepotwierdzone adresy. Weryfikacja adresów e-mail w czasie rzeczywistym zatrzymuje je już na wejściu.
Pomaga także chronić przed oszustwami: sprawdzenie w czasie rzeczywistym może oznaczyć jednorazową skrzynkę, zanim konto zostanie utworzone.
Walidacja emaili w czasie rzeczywistym a walidacja zbiorcza
Oba podejścia wykorzystują te same kontrole. Różnią się momentem ich wykonywania oraz ilością dostępnego czasu.
- Walidacja w czasie rzeczywistym odbywa się dla jednego adresu naraz, w ramach żądania użytkownika. Ma ścisły limit czasu, często znacznie krótszy niż sekunda, ponieważ powolny formularz powoduje utratę rejestracji. Zapobiega przedostawaniu się nieprawidłowych danych.
- Walidacja zbiorcza obejmuje całą listę i działa w tle. Może trwać minuty lub godziny, a nikt nie czeka przed ekranem. Oczyszcza dane, które już znajdują się w systemie, na przykład przed dużą kampanią lub po imporcie do CRM.
Większość zespołów potrzebuje obu metod. Kontrole w czasie rzeczywistym utrzymują czystość nowych danych, a okresowa zbiorcza weryfikacja wykrywa adresy, które z czasem przestały działać, na przykład należące do pracowników, którzy opuścili firmę. Aby zobaczyć dokładniejsze porównanie, zapoznaj się z artykułem walidacja emaili w czasie rzeczywistym a walidacja zbiorcza.
Co faktycznie sprawdza kontrola w czasie rzeczywistym
API do walidacji adresów e-mail przeprowadza serię kontroli — od najtańszych do najbardziej kosztownych. Każda z nich eliminuje inny rodzaj nieprawidłowego adresu.
Składnia
Pierwsza kontrola dotyczy formatu. Czy występuje dokładnie jeden znak @? Czy część lokalna składa się z dozwolonych znaków? Czy domena wygląda jak domena? Kontrola składni odrzuca oczywiste błędy, takie jak john@@example lub jane.example.com. Jest szybka i nie wymaga połączenia z siecią. Jednak poprawna składnia nie mówi nic o tym, czy skrzynka pocztowa istnieje.
Domena i rekordy MX
Następnie API wyszukuje domenę w DNS. Domena bez rekordów MX nie może odbierać wiadomości e-mail, więc adres w takiej domenie jest bezużyteczny, niezależnie od tego, jak poprawnie wygląda. Pozwala to wykrywać błędnie zapisane domeny i nieaktywne domeny firmowe. BillionVerify zwraca znalezione hosty MX w mx_records, a domain_suggestion może zawierać prawdopodobną poprawkę, gdy domena wygląda jak literówka popularnej domeny.
Sygnały adresów tymczasowych, funkcyjnych i dostawców bezpłatnych usług
Niektóre adresy istnieją, ale nadal słabo pasują do Twojego produktu:
- Adresy tymczasowe pochodzą z usług oferujących tymczasowe skrzynki odbiorcze i zwykle przestają działać w ciągu kilku godzin. Zobacz jak działa wykrywanie tymczasowych adresów e-mail.
- Adresy funkcyjne, takie jak
info@lubsupport@, prowadzą do zespołu, a nie do konkretnej osoby. Zwykle można na nie dostarczyć wiadomość, ale zazwyczaj rzadziej angażują odbiorców. - Adresy od bezpłatnych dostawców, takie jak Gmail, są normalne w przypadku konsumentów, ale warto je odnotować w formularzu B2B.
API zwraca te informacje jako flagi (is_disposable, is_role, is_free), dzięki czemu możesz podejmować decyzje zależnie od produktu.
Domeny catch-all
Niektóre serwery pocztowe akceptują wiadomości dla dowolnego adresu w swojej domenie — prawdziwego lub nie. W przypadku takich domen catch-all kontrola skrzynki pocztowej nie może potwierdzić, że konkretna skrzynka istnieje. Wynik catch-all nie jest złym wynikiem. Oznacza, że pewność jest mniejsza, dlatego wynik punktowy ma większe znaczenie niż etykieta. Wykrywanie adresów e-mail catch-all wyjaśnia, jak to działa i dlaczego ma znaczenie.
Kontrola skrzynki pocztowej SMTP
Najbardziej szczegółowa kontrola pyta serwer pocztowy odbiorcy przez SMTP, czy skrzynka zaakceptowałaby wiadomość, bez jej wysyłania. Wykrywa adresy w prawidłowych domenach, które już nie istnieją, na przykład skrzynkę byłego pracownika. Jest to również najwolniejszy etap, ponieważ zależy od serwera innej osoby. W BillionVerify można go kontrolować za pomocą parametru check_smtp. Jeśli go pominiesz, API przeprowadzi kontrolę SMTP; wyślij check_smtp: false, aby ją pominąć.
Reputacja domeny
BillionVerify może również zwrócić obiekt domain_reputation z wynikami sprawdzania czarnej listy dla adresu IP serwera pocztowego domeny. Ma on wyłącznie charakter informacyjny: nie zmienia statusu, wyniku punktowego ani kosztu.
Jak wywołać API walidacji adresów e-mail w czasie rzeczywistym
W BillionVerify pojedyncze sprawdzenie w czasie rzeczywistym wymaga jednego żądania HTTPS. Bazowy URL to https://api.billionverify.com/v1, a klucz API umieść w nagłówku BV-API-KEY. Przechowuj ten klucz na swoim serwerze. Nigdy nie umieszczaj go w kodzie przeglądarki.
Oto minimalne żądanie oparte na dokumentacji 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}'
Żądanie przyjmuje trzy parametry:
| Parametr | Wartość domyślna | Działanie |
|---|---|---|
email | wymagany | Adres do zwalidowania |
check_smtp | włączone | Ustaw false, aby pominąć sprawdzenie skrzynki pocztowej SMTP na żywo |
force_refresh | false | Pomija wyniki z pamięci podręcznej; świeży wynik jest rozliczany jak nowe sprawdzenie |
Pomyślna odpowiedź umieszcza wynik w standardowej kopercie. Oto skrócony przykład dla adresu, na który można dostarczyć wiadomość:
{
"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
}
}
Jeśli wolisz SDK, BillionVerify udostępnia oficjalne wersje dla Node.js, Python, TypeScript, Go, PHP i Java. W Node.js polecenie npm install billionverify-sdk zapewnia klienta z metodą verify; w Pythonie pakiet nosi nazwę billionverify.
Odczytywanie odpowiedzi: status, wynik i powód
Pole status jest tym, na którym opiera się większość gałęzi kodu. Oto, co oznacza każdy status, oraz rozsądne ustawienie domyślne dla formularza rejestracyjnego:
| Status | Znaczenie | Domyślne działanie w formularzu rejestracyjnym |
|---|---|---|
valid | Skrzynka pocztowa istnieje i może odbierać wiadomości | Zaakceptuj |
invalid | Adres nie istnieje lub nie może odbierać wiadomości | Zablokuj i poproś o inny adres |
disposable | Tymczasowa skrzynka odbiorcza | Zablokuj lub zaakceptuj z ograniczeniami |
catchall | Domena akceptuje każdy adres | Zaakceptuj i monitoruj |
role | Współdzielona skrzynka odbiorcza, np. info@ | Zaakceptuj, ewentualnie oznacz dla działu sprzedaży |
unknown | Nie udało się potwierdzić dostarczalności | Zaakceptuj i sprawdź ponownie później |
Pole score daje dokładniejszy sygnał w zakresie od 0 do 1. Orientacyjnie wyniki valid mają wartość od 0.85 do 1.0, catchall około 0.55–0.75, unknown od 0.3 do 0.6, disposable 0,1, a invalid 0. Wynik role zachowuje wynik bazowego sprawdzenia. Możesz użyć wyniku do ustawienia własnego progu dla przypadków granicznych, na przykład akceptować adresy catch-all tylko powyżej określonego wyniku w formularzu o wysokiej wartości.
Pole reason wyjaśnia werdykt. Wynik invalid może zawierać invalid_syntax, no_mx_records lub mailbox_not_found, a każdy z nich wskazuje inną wiadomość dla użytkownika. Problem ze składnią oznacza „sprawdź format”. Brak skrzynki oznacza „ta skrzynka odbiorcza nie istnieje”. Strona powodów weryfikacji zawiera listę wszystkich powodów i wskazuje, które powody unknown warto ponownie sprawdzić.
Dwa pola pomagają użytkownikowi bezpośrednio: domain_suggestion może zasilać podpowiedź „Czy chodziło Ci o gmail.com?”, a is_disposable wyjaśnia, dlaczego adres jednorazowy został odrzucony.
Projektowanie procesu rejestracji z uwzględnieniem budżetu opóźnienia
Najtrudniejsze jest dodanie weryfikacji do formularza bez jego spowalniania. Zacznij od ustalenia budżetu. Określ, jak długo możesz wstrzymywać użytkownika, na przykład od 300 do 500 milisekund po wysłaniu formularza. Od tej wartości zależy cała reszta.
Materiały produktowe BillionVerify podają, że wyniki z pamięci podręcznej są dostępne w czasie poniżej 200 ms, a pełna weryfikacja SMTP trwa średnio od 1 do 3 sekund. Ta różnica daje Ci dwa dobre rozwiązania:
- Pełna weryfikacja z limitem czasu. Wywołaj API z włączonym SMTP i limitem czasu wynoszącym od 2 do 3 sekund. Większość odpowiedzi nadejdzie na czas i zwróci jednoznaczny wynik
validlubinvalid. Jeśli limit czasu zostanie przekroczony, zezwól na kontynuowanie procesu i wykonaj ponowną weryfikację później. - Szybka weryfikacja teraz, dokładna później. Wywołaj API z wartością
check_smtp: false. Pozwala to rozstrzygnąć tylko oczywiste przypadki: nieprawidłową składnię, domenę bez rekordów MX oraz adresy jednorazowe i funkcyjne. Adres w działającej domenie wróci jakounknownz przyczynąsmtp_unverifiable, co jest oczekiwane. Zaakceptuj go, a następnie wykonaj drugie wywołanie z włączonym SMTP w zadaniu działającym w tle. Jeśli skrzynka pocztowa nie istnieje, oznacz konto i poproś użytkownika o potwierdzenie adresu.
Pomocnych jest również kilka praktyk frontendowych:
- Weryfikuj po opuszczeniu pola lub wysłaniu formularza, a nie po każdym naciśnięciu klawisza. Sprawdzanie
j,jo,johmarnuje wywołania i kredyty. - Najpierw wykonuj lokalne sprawdzanie składni, aby uniknąć dodatkowego żądania przy oczywistych błędach.
- Wywołuj API z backendu. Twój serwer przechowuje klucz API i zapisuje wynik, a przeglądarka wyświetla tylko rezultat.
Informacje o szczegółach UX, takich jak treść komunikatów, miejsce wyświetlania błędów i moment pokazania podpowiedzi, znajdziesz w artykule weryfikacja adresu e-mail podczas rejestracji.
Odrzucać czy przepuszczać? Obsługa przekroczeń czasu i nieznanych wyników
Wzorzec, który sprawdza się w większości produktów, to: odrzucaj przy jednoznacznych błędach, przepuszczaj przy niepewności.
- Odrzucanie oznacza zablokowanie rejestracji. Zrób to, gdy API informuje, że adres jest wyraźnie nieprawidłowy:
invalidzinvalid_syntaxlubno_mx_records, albo gdy adres jestdisposablew formularzu, w którym jednorazowe konta powodują szkody. - Przepuszczanie oznacza zezwolenie użytkownikowi na przejście i późniejsze podjęcie dalszych działań. Zrób to, gdy wynik jest niepewny: status
unknown, domena typu catch-all lub własne przekroczenie czasu oczekiwania przed odpowiedzią API.
Dlaczego nie blokować również niepewnych adresów? Za wieloma z nich stoją prawdziwi ludzie. Firmowe serwery pocztowe często stosują greylisting lub ograniczają częstotliwość kontroli SMTP, więc ich blokowanie kosztuje realne rejestracje. Zaakceptuj adres, oznacz rekord i sprawdź go ponownie później.
Ustaw po stronie klienta limit czasu dla wywołania API zgodny z założonym budżetem opóźnienia. Gdy limit zostanie przekroczony, potraktuj wynik jako unknown: zaakceptuj go, zapisz flagę i dodaj ponowną kontrolę w tle do kolejki. Ponawiaj sprawdzanie wyników unknown później, a nie w ramach tego samego żądania.
Przykład: Walidacja adresu e-mail podczas rejestracji w Node.js
Poniższy szkic pokazuje szybką kontrolę (projekt 2) w module obsługującym rejestrację. Wykorzystuje udokumentowany punkt końcowy REST i pola odpowiedzi, limit czasu oraz opisane powyżej zasady fail open lub closed. Dostosuj nazwy do swojego frameworka.
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 {
// Limit czasu lub błąd sieci: zezwól i sprawdź ponownie w tle.
return { allow: true, recheck: true };
} finally {
clearTimeout(timer);
}
}
Bez SMTP większość rzeczywistych adresów wraca ze statusem unknown i otrzymuje flagę recheck. Po zapisaniu konta zadanie w tle wywołuje ten sam punkt końcowy z włączonym SMTP dla każdego rekordu oznaczonego flagą recheck. Samouczek Node.js przedstawia pełniejszą konfigurację, w tym oficjalny SDK. To samo żądanie działa w Pythonie lub dowolnym języku z klientem HTTP.
Limity zapytań, buforowanie i koszty
Kontrola w czasie rzeczywistym znajduje się na ścieżce rejestracji, więc jej limity stają się Twoimi limitami. Zaplanuj to.
Limity zapytań. BillionVerify chroni swoją przepustowość za pomocą limitów przypisanych do kont. Po osiągnięciu limitu API zwraca HTTP 429 z kodem 1003 i nagłówkiem Retry-After. Zmniejsz tempo i ponów próbę, a także zachowaj własną regułę fail-open, aby limit nigdy nie blokował prawdziwego użytkownika.
Buforowanie. Wyniki są buforowane, dlatego powtórne kontrole zwracają wynik szybko. Ponowna kontrola adresu, który Twoje konto zweryfikowało w ciągu ostatnich 24 godzin, jest bezpłatna. Używaj force_refresh: true tylko wtedy, gdy naprawdę potrzebujesz świeżej odpowiedzi, ponieważ pomija bufor i jest rozliczana jak nowa kontrola.
Koszt. Pojedyncza kontrola zwykle wykorzystuje 1 kredyt, wykazywany w credits_used. Każdy wynik unknown jest bezpłatny, podobnie jak błędy składni. Weryfikuj dane podczas wysyłania formularza, a nie przy każdym naciśnięciu klawisza, i nie sprawdzaj ponownie adresu, który został niedawno zweryfikowany. BillionVerify przyznaje 20 bezpłatnych kredytów każdego dnia logowania, maksymalnie 600 miesięcznie, co wystarcza do zbudowania i przetestowania integracji. Płatne pakiety kredytów są wymienione na stronie cennika.
Poza formularzem: partie, pliki i webhooki
Walidacja w czasie rzeczywistym obejmuje nowe adresy pojedynczo. W pozostałych przypadkach to samo API oferuje inne punkty wejścia:
- Małe partie.
POST /verify/bulksprawdza do 50 adresów w jednym żądaniu, co sprawdza się przy synchronizacji CRM lub na ekranie importu. - Duże listy.
POST /verify/fileprzyjmuje plik CSV, TXT lub XLSX i przetwarza go w tle. - Webhooki. Zamiast odpytywać o status zadania plikowego, zarejestruj webhook dla zdarzeń
file.completedifile.failed. Zobacz przewodnik po webhookach weryfikacji adresów e-mail, aby poznać sprawdzanie podpisów i ponawianie prób. - Sprawdzanie wyłącznie jednorazowych adresów.
POST /verify/disposableodpowiada tylko na pytanie, czy adres jest jednorazowy, i nie wykorzystuje kredytów.
Typowa konfiguracja: sprawdzanie w czasie rzeczywistym przy każdym formularzu, nocna partia dla rekordów oznaczonych jako recheck oraz zadanie plikowe przed dużymi kampaniami.
Lista kontrolna walidacji wiadomości e-mail w czasie rzeczywistym
Przed wdrożeniem przejdź przez tę listę:
- Klucz API znajduje się na serwerze, nigdy w przeglądarce.
- Składnia jest sprawdzana lokalnie przed wywołaniem API.
- Ścieżka żądania używa
check_smtp: falseoraz limitu czasu dopasowanego do budżetu opóźnień. - Statusy
invalididisposablemają jasne, konkretne komunikaty o błędach. - Statusy
unknown,catchalli przekroczenia limitu czasu są przepuszczane i umieszczane w kolejce do ponownego sprawdzenia. domain_suggestionzapewnia podpowiedź dotyczącą literówki.- Odpowiedzi 429 powodują wycofanie bez blokowania użytkowników.
- Wyniki są przechowywane razem z rekordem użytkownika, dzięki czemu później można mierzyć współczynniki odrzuceń.
FAQ
Czym jest API do walidacji adresów e-mail w czasie rzeczywistym?
API do walidacji adresów e-mail w czasie rzeczywistym sprawdza pojedynczy adres e-mail podczas wysyłania formularza przez użytkownika i zwraca wynik w ułamku sekundy. Wykonuje kontrole składni, domeny, MX, adresów jednorazowych, ról i catch-all, a opcjonalnie także sprawdzenie skrzynki pocztowej przez SMTP, dzięki czemu aplikacja może zaakceptować, zablokować lub oznaczyć adres, zanim trafi on do bazy danych.
Czym walidacja adresów e-mail w czasie rzeczywistym różni się od walidacji zbiorczej?
Walidacja adresów e-mail w czasie rzeczywistym sprawdza jeden adres naraz w ramach żądania użytkownika i musi odpowiedzieć szybko. Walidacja zbiorcza sprawdza całą listę w tle i może trwać znacznie dłużej. Używaj sprawdzania w czasie rzeczywistym, aby utrzymywać nowe dane w czystości, a kontroli zbiorczej do oczyszczania danych, które już posiadasz.
Czy powinienem uruchamiać sprawdzanie SMTP przy każdej rejestracji?
To zależy od Twojego limitu opóźnienia. Sprawdzanie SMTP potwierdza istnienie skrzynki pocztowej, więc bez niego większość prawidłowych adresów zwraca wynik unknown. Jeśli możesz poczekać 2–3 sekundy, uruchamiaj je podczas wysyłania formularza z limitem czasu. Jeśli nie, wykonuj szybkie sprawdzenie z check_smtp: false, a sprawdzanie SMTP uruchamiaj w zadaniu wykonywanym w tle.
Co zrobić z wynikami catch-all i unknown?
Zaakceptuj je i sprawdź ponownie później. Domena catch-all akceptuje każdy adres, więc sprawdzenie skrzynki pocztowej nie może potwierdzić istnienia skrzynki, a wynik unknown oznacza, że sprawdzanie nie mogło się zakończyć. Blokowanie tych użytkowników powoduje utratę prawidłowych rejestracji; oznaczanie ich i ponowne sprawdzanie pomaga utrzymać czyste dane bez obniżania konwersji.
Czy mogę wywoływać API sprawdzające adresy e-mail z przeglądarki?
Nie. Spowodowałoby to ujawnienie klucza API. Wywołuj API z backendu i zwracaj wyłącznie decyzję.
Jak szybka jest weryfikacja adresów e-mail w czasie rzeczywistym?
W BillionVerify wyniki z pamięci podręcznej są zwracane w czasie krótszym niż 200 ms, a pełne sprawdzenie SMTP trwa średnio 1–3 sekundy. Dlatego szybkie sprawdzenie bez SMTP powinno być wykonywane w ramach żądania, a sprawdzanie SMTP w tle.
Ile kosztuje API do walidacji adresów e-mail?
W BillionVerify pojedyncze sprawdzenie zwykle zużywa 1 kredyt, a każdy wynik unknown jest bezpłatny. Otrzymujesz 20 bezpłatnych kredytów każdego dnia, gdy się logujesz, maksymalnie 600 miesięcznie, a płatne pakiety kredytów znajdziesz na stronie cennika. force_refresh pomija pamięć podręczną i jest rozliczane jak nowe sprawdzenie.
Zacznij weryfikować adresy e-mail w czasie rzeczywistym
Weryfikacja adresów e-mail w czasie rzeczywistym oznacza mniej odrzuceń, mniej fałszywych kont i mniej użytkowników traconych z powodu literówki. Umieść szybkie sprawdzenie w ścieżce żądania, przenieś wolne sprawdzenie do tła i pozwól, aby jednoznaczne błędy blokowały, podczas gdy niepewne wyniki przechodziły dalej. Utwórz bezpłatne konto BillionVerify, uzyskaj klucz API i wykonaj pierwsze wywołanie API walidacji adresu e-mail, korzystając z powyższej dokumentacji.