Realtime e-mailvalidatie-API: Gids voor ontwikkelaars

Realtime e-mailvalidatie controleert een adres terwijl de gebruiker nog op je formulier is. De controle wordt uitgevoerd in de paar honderd milliseconden tussen ‘Verzenden’ en het volgende scherm, en beantwoordt één vraag: moet dit adres in je database terechtkomen? Een realtime e-mailvalidatie-API neemt die beslissing voor je. De API controleert de syntaxis, het domein en de MX-records, signalen voor wegwerp- en rolgebaseerde adressen, catch-all-gedrag en, wanneer je daarom vraagt, de mailbox zelf. Vervolgens retourneert de API een gestructureerd resultaat waarop je code kan handelen.

Deze handleiding is bedoeld voor ontwikkelaars die deze controle toevoegen aan een registratie-, checkout- of leadformulier. Je leest wat de controles doen, hoe je een API aanroept, hoe je elke status omzet in een productbeslissing en hoe je snel blijft wanneer een mailserver traag is. De voorbeelden gebruiken de e-mailvalidatie-API van BillionVerify, maar het ontwerpadvies is van toepassing op elke provider.

Wat Is Real-Time E-mailvalidatie?

Real-time e-mailvalidatie is een controle die wordt uitgevoerd op het moment dat een adres wordt ingevoerd, niet dagen later wanneer een campagne wordt verzonden. De gebruiker typt een adres. Je frontend of backend stuurt het naar een e-mailchecker-API. De API antwoordt met een status zoals valid, invalid of catchall, plus de onderliggende signalen. Je applicatie staat de registratie vervolgens toe, blokkeert deze of vraagt de gebruiker een typefout te herstellen.

Het draait om timing. Een typefout zoals gmial.com kost niets om te herstellen zolang de gebruiker nog op het formulier zit. Nadat de welkomstmail is teruggestuurd, kost dezelfde typefout je de klant. Ongeldige adressen schaden ook je afzenderreputatie, omdat elke harde bounce mailboxproviders vertelt dat je naar onbevestigde adressen verzendt. Real-time e-mailverificatie houdt ze bij de deur tegen.

Het helpt ook tegen fraude: een real-time controle kan een wegwerpinbox markeren voordat het account bestaat.

Real-time versus bulk-e-mailvalidatie

Beide benaderingen gebruiken dezelfde controles. Ze verschillen in wanneer ze worden uitgevoerd en hoeveel tijd ze hebben.

• Real-timevalidatie wordt per keer op één adres uitgevoerd, binnen een gebruikersverzoek. Er is een strikt tijdsbudget, vaak ruim minder dan een seconde, omdat een traag formulier inschrijvingen kost. Zo voorkomt het dat onjuiste gegevens worden toegevoegd.
• Bulkvalidatie wordt op een volledige lijst uitgevoerd, op de achtergrond. Dit kan minuten of uren duren en niemand wacht voor een scherm. Het schoont gegevens op die al in je systeem staan, bijvoorbeeld vóór een grote campagne of na een CRM-import.

De meeste teams hebben beide nodig. Real-timecontroles houden nieuwe gegevens schoon en een periodieke bulkverificatie vangt adressen op die na verloop van tijd ongeldig zijn geworden, zoals medewerkers die een bedrijf hebben verlaten. Zie voor een uitgebreidere vergelijking real-time versus bulk-e-mailvalidatie.

Wat een real-time controle daadwerkelijk test

Een e-mailvalidatie-API voert een reeks controles uit, van goedkoop tot duur. Elke controle sluit een ander type ongeldig adres uit.

Syntaxis

De eerste controle betreft de indeling. Staat er precies één @? Bestaat het lokale deel uit toegestane tekens? Ziet het domein eruit als een domein? Syntaxis wijst duidelijke rommel af, zoals john@@example of jane.example.com. Dit gaat snel en vereist geen netwerkoproep. Maar perfecte syntaxis zegt niets over de vraag of de mailbox bestaat.

Domein- en MX-records

Vervolgens zoekt de API het domein op in DNS. Een domein zonder MX-records kan geen e-mail ontvangen, dus een adres daar is nutteloos, hoe netjes het er ook uitziet. Dit vangt verkeerd gespelde domeinen en niet meer actieve bedrijfsdomeinen op. BillionVerify geeft de gevonden MX-hosts terug in mx_records, en domain_suggestion kan een waarschijnlijke correctie bevatten wanneer het domein lijkt op een typefout van een veelgebruikt domein.

Signalen voor tijdelijke, rol- en gratis-provideradressen

Sommige adressen bestaan wel, maar passen toch minder goed bij je product:

• Tijdelijke adressen komen van tijdelijke inboxdiensten en werken meestal binnen enkele uren niet meer. Zie hoe detectie van tijdelijke e-mail werkt.
• Roladressen zoals info@ of support@ gaan naar een team, niet naar één persoon. Ze zijn meestal afleverbaar, maar leveren doorgaans minder betrokkenheid op.
• Adressen van gratis providers zoals Gmail zijn normaal voor consumenten, maar het is de moeite waard om ze op een B2B-formulier vast te leggen.

De API rapporteert deze als vlaggen (is_disposable, is_role, is_free), zodat je per product kunt beslissen.

Catch-all-domeinen

Sommige mailservers accepteren e-mail voor elk adres binnen hun domein, bestaand of niet. Voor deze catch-all-domeinen kan een mailboxcontrole niet bewijzen dat een specifieke inbox bestaat. Een catch-all-resultaat is geen slecht resultaat. Het betekent dat de zekerheid lager is, waardoor de score belangrijker is dan het label. Detectie van catch-all-e-mail legt uit hoe dit werkt en waarom het belangrijk is.

SMTP-mailboxcontrole

De grondigste controle vraagt de mailserver van de ontvanger via SMTP of de mailbox een bericht zou accepteren, zonder er een te verzenden. Hiermee worden adressen op echte domeinen gevonden die niet meer bestaan, zoals de inbox van een voormalige medewerker. Het is ook de langzaamste stap, omdat deze afhankelijk is van de server van iemand anders. In BillionVerify wordt dit geregeld met de parameter check_smtp. Als je deze weglaat, voert de API de SMTP-controle uit; stuur check_smtp: false mee om deze over te slaan.

Domeinreputatie

BillionVerify kan ook een object domain_reputation teruggeven met blacklistresultaten voor het IP-adres van de mailserver van het domein. Dit is uitsluitend ter informatie: het verandert de status, de score of de kosten niet.

Een real-time e-mailvalidatie-API aanroepen

Met BillionVerify is één real-time controle één HTTPS-verzoek. De basis-URL is https://api.billionverify.com/v1 en je API-sleutel wordt meegegeven in de header BV-API-KEY. Bewaar die sleutel op je server. Neem deze nooit op in browsercode.

Hier is een minimaal verzoek, gebaseerd op de API-referentie:

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

Het verzoek bevat drie parameters:

Een geslaagd antwoord verpakt het resultaat in een standaardomhulsel. Hier is een verkort voorbeeld voor een afleverbaar adres:

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

Als je liever een SDK gebruikt, publiceert BillionVerify officiële SDK's voor Node.js, Python, TypeScript, Go, PHP en Java. In Node.js installeert npm install billionverify-sdk een client met een verify-methode; in Python heet het pakket billionverify.

De respons lezen: status, score en reden

Het veld status is waarop de meeste codevertakkingen gebaseerd zijn. Dit is wat elke status betekent en wat een verstandige standaardinstelling voor een registratieformulier is:

De score geeft een nauwkeuriger signaal tussen 0 en 1. Als grove richtlijn scoren valid-resultaten 0,85 tot 1,0, catchall ongeveer 0,55 tot 0,75, unknown 0,3 tot 0,6, disposable 0,1 en invalid 0. Een role-resultaat behoudt de score van de onderliggende controle. Je kunt de score gebruiken om je eigen drempel voor twijfelgevallen in te stellen, bijvoorbeeld om catch-all-adressen alleen boven een bepaalde score op een formulier met hoge waarde te accepteren.

Het veld reason legt het oordeel uit. Een invalid-resultaat kan gepaard gaan met invalid_syntax, no_mx_records of mailbox_not_found, waarbij elke reden naar een ander bericht voor de gebruiker verwijst. Een syntaxprobleem betekent: "controleer de indeling". Een ontbrekende mailbox betekent: "deze inbox bestaat niet". De pagina met verificatieredenen bevat elke reden en vermeldt welke unknown-redenen het waard zijn om opnieuw te proberen.

Twee velden helpen de gebruiker rechtstreeks: domain_suggestion kan een hint als "Bedoelde je gmail.com?" aansturen, en is_disposable legt uit waarom een wegwerpadres is geweigerd.

De signupflow ontwerpen rond een latentiebudget

Het lastigste is de controle in een formulier inpassen zonder het formulier te vertragen. Begin met een budget. Bepaal hoe lang je bereid bent de gebruiker te laten wachten, bijvoorbeeld 300 tot 500 milliseconden na het verzenden. Al het andere volgt uit dat getal.

In de productteksten van BillionVerify staan gecachte resultaten onder 200 ms en duurt een volledige SMTP-controle gemiddeld 1–3 seconden. Dat verschil laat je twee goede ontwerpen:

1. Volledige controle met een time-out. Roep de API aan met SMTP ingeschakeld en een time-out van 2–3 seconden. De meeste antwoorden komen op tijd binnen en geven je een duidelijk valid of invalid. Als de time-out afgaat, laat je de aanvraag doorgaan en voer je later opnieuw een controle uit.
2. Nu snel controleren, later grondig controleren. Roep de API aan met check_smtp: false. Hiermee worden alleen duidelijke gevallen afgehandeld: onjuiste syntaxis, een domein zonder MX-records en wegwerp- en roladressen. Een adres op een werkend domein komt terug als unknown met de reden smtp_unverifiable, wat verwacht is. Accepteer het en voer daarna vanuit een achtergrondtaak een tweede aanroep uit met SMTP ingeschakeld. Als de mailbox niet bestaat, markeer je het account en vraag je de gebruiker het adres te bevestigen.

Een paar frontend-gewoonten helpen ook:

• Valideer bij het verlaten van het veld of na het verzenden, niet bij elke toetsaanslag. j, jo, joh controleren verspilt aanroepen en credits.
• Voer eerst lokale syntaxiscontroles uit om een roundtrip voor duidelijke fouten te besparen.
• Roep de API aan vanuit je backend. Je server bewaart de API-sleutel en registreert het resultaat; de browser toont alleen de uitkomst.

Bekijk voor UX-details zoals formulering, de plaatsing van fouten en wanneer je een hint toont e-mailverificatie tijdens signup.

Fail Open of Fail Closed? Omgaan met time-outs en onbekende gevallen

Het patroon dat voor de meeste producten werkt, is: bij duidelijke fouten fail closed, bij onzekerheid fail open.

• Fail closed betekent dat je de registratie blokkeert. Doe dit wanneer de API aangeeft dat het adres duidelijk ongeldig is: invalid met invalid_syntax of no_mx_records, of een disposable adres op een formulier waar wegwerpaccounts schade veroorzaken.
• Fail open betekent dat je de gebruiker doorlaat en later opvolgt. Doe dit wanneer het antwoord onzeker is: een unknown-status, een catch-all-domein of wanneer je eigen time-out afgaat voordat de API antwoord geeft.

Waarom onzekere adressen dan ook blokkeren? Achter veel daarvan zitten echte mensen. Bedrijfsservers voor e-mail gebruiken vaak greylisting of beperken SMTP-controles, dus ze blokkeren kost je echte registraties. Accepteer het adres, voeg een label toe aan het record en controleer het later opnieuw.

Stel aan de clientzijde een time-out in voor je API-aanroep die past bij je latencybudget. Wanneer die afgaat, behandel je het resultaat als unknown: accepteer het, sla een markering op en zet een controle op de achtergrond in de wachtrij. Probeer unknown-resultaten later opnieuw in plaats van binnen het verzoek.

Voorbeeld: Een e-mailadres valideren bij registratie in Node.js

De onderstaande schets toont de snelle controle (ontwerp 2) in een registratiehandler. Deze gebruikt het gedocumenteerde REST-eindpunt en de responsvelden, een time-out en de hierboven beschreven regels voor fail open of fail closed. Pas de namen aan je framework aan.

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);
  }
}

Zonder SMTP komen de meeste echte adressen terug als unknown en krijgen ze de vlag recheck. Nadat het account is opgeslagen, roept een achtergrondtaak hetzelfde eindpunt aan met SMTP ingeschakeld voor elk record dat is gemarkeerd met recheck. De Node.js-tutorial leidt je door een uitgebreidere configuratie, inclusief de officiële SDK. Hetzelfde verzoek werkt vanuit Python of elke taal met een HTTP-client.

Limieten, caching en kosten

Een realtimecontrole maakt deel uit van je registratieproces, dus de limieten ervan worden jouw limieten. Plan hiervoor.

Limieten. BillionVerify beschermt zijn capaciteit met limieten per account. Wanneer je er een bereikt, retourneert de API HTTP 429 met code 1003 en een Retry-After-header. Wacht even en probeer het opnieuw, en houd je eigen fail-open-regel actief, zodat een limiet nooit een echte gebruiker blokkeert.

Caching. Resultaten worden gecachet, waardoor herhaalde controles snel worden uitgevoerd. Een adres opnieuw controleren dat je account in de afgelopen 24 uur heeft geverifieerd, is gratis. Gebruik force_refresh: true alleen wanneer je echt een nieuw antwoord nodig hebt, omdat hiermee de cache wordt overgeslagen en de controle wordt gefactureerd als een nieuwe controle.

Kosten. Eén controle gebruikt normaal gesproken 1 credit, weergegeven in credits_used. Elk unknown-resultaat is gratis, net als syntaxisfouten. Valideer bij het verzenden in plaats van bij elke toetsaanslag, en controleer een adres niet opnieuw als je het onlangs hebt geverifieerd. BillionVerify geeft je elke dag dat je inlogt 20 gratis credits, tot 600 per maand. Dat is genoeg om een integratie te bouwen en te testen. Betaalde creditpakketten staan vermeld op de prijspagina.

Verder dan het formulier: batches, bestanden en webhooks

Realtimevalidatie controleert nieuwe adressen één voor één. Voor al het andere heeft dezelfde API nog andere toegangspunten:

• Kleine batches. POST /verify/bulk controleert maximaal 50 adressen in één verzoek, geschikt voor een CRM-synchronisatie of een imports scherm.
• Grote lijsten. POST /verify/file accepteert een CSV-, TXT- of XLSX-bestand en verwerkt dit op de achtergrond.
• Webhooks. Registreer in plaats van een bestandsjob te pollen een webhook voor file.completed- en file.failed-gebeurtenissen. Bekijk de handleiding voor webhooks voor e-mailverificatie voor handtekeningcontroles en nieuwe pogingen.
• Alleen wegwerpcontroles. POST /verify/disposable beantwoordt alleen de vraag of het adres wegwerpbaar is en gebruikt geen credits.

Een veelgebruikte opzet: realtimecontroles op elk formulier, een nachtelijke batch voor records met de markering recheck, en een bestandsjob vóór grote campagnes.

Checklist voor real-time e-mailvalidatie

Voordat je publiceert, loop je deze lijst door:

• De API-sleutel staat op de server, nooit in de browser.
• De syntaxis wordt lokaal gecontroleerd vóór de API-aanroep.
• Het aanvraagpad gebruikt check_smtp: false en een time-out die past binnen je latentiebudget.
• invalid en disposable hebben duidelijke, specifieke foutmeldingen.
• unknown, catchall en time-outs falen open en worden in de wachtrij geplaatst voor een nieuwe controle.
• domain_suggestion levert een typfoutmelding.
• 429-responses bouwen back-off op zonder gebruikers te blokkeren.
• Resultaten worden opgeslagen bij het gebruikersrecord, zodat je later bouncepercentages kunt meten.

FAQ

Wat is een real-time e-mailvalidatie-API?

Een real-time e-mailvalidatie-API controleert één e-mailadres terwijl een gebruiker een formulier verzendt en geeft binnen een fractie van een seconde een oordeel terug. De API voert controles uit op syntaxis, domein, MX, tijdelijke adressen, rolgebaseerde adressen en catch-all, en optioneel een SMTP-mailboxcontrole, zodat je app het adres kan accepteren, blokkeren of markeren voordat het je database bereikt.

Waarin verschilt real-time e-mailvalidatie van bulkvalidatie?

Real-time e-mailvalidatie controleert één adres per keer binnen een gebruikersverzoek en moet snel antwoorden. Bulkvalidatie controleert een volledige lijst op de achtergrond en kan veel langer duren. Gebruik real-time controles om nieuwe gegevens schoon te houden en bulkcontroles om gegevens die je al hebt op te schonen.

Moet ik de SMTP-controle bij elke registratie uitvoeren?

Dat hangt af van je latentiebudget. De SMTP-controle bevestigt of een mailbox bestaat, dus zonder deze controle krijgen de meeste echte adressen de status unknown. Als je 2–3 seconden kunt wachten, voer je de controle uit bij het verzenden, met een time-out. Zo niet, voer je de snelle controle uit met check_smtp: false en doe je de SMTP-controle in een achtergrondtaak.

Wat moet ik doen met catch-all- en onbekende resultaten?

Accepteer ze en controleer ze later opnieuw. Een catch-all-domein accepteert elk adres, waardoor een mailboxcontrole niet kan bewijzen dat de inbox bestaat; een onbekend resultaat betekent dat de controle niet kon worden voltooid. Als je deze gebruikers blokkeert, verlies je echte registraties. Door ze te taggen en opnieuw te controleren, houd je je gegevens schoon zonder je conversie te schaden.

Kan ik de e-mailchecker-API vanuit de browser aanroepen?

Nee. Daarmee stel je je API-sleutel bloot. Roep de API aan vanuit je backend en geef alleen de beslissing terug.

Hoe snel is real-time e-mailverificatie?

Met BillionVerify worden resultaten uit de cache binnen 200 ms teruggegeven en duurt een volledige SMTP-controle gemiddeld 1–3 seconden. Daarom hoort de snelle controle zonder SMTP in het aanvraagpad en de SMTP-controle op de achtergrond.

Hoeveel kost een e-mailvalidatie-API?

In BillionVerify gebruikt één controle normaal gesproken 1 credit en elk resultaat unknown is gratis. Je krijgt elke dag dat je inlogt 20 gratis credits, tot maximaal 600 per maand, en betaalde creditpakketten vind je op de prijspagina. force_refresh slaat de cache over en wordt gefactureerd als een nieuwe controle.

Begin met het realtime valideren van e-mailadressen

Realtime e-mailvalidatie betekent minder bounces, minder nepaccounts en minder gebruikers die door een typefout verloren gaan. Voer een snelle controle uit in het aanvraagpad, verplaats de trage controle naar de achtergrond en laat duidelijke fouten blokkeren terwijl onzekere resultaten worden doorgelaten. Maak een gratis BillionVerify-account aan, ontvang een API-sleutel en voer je eerste API-aanroep voor het valideren van een e-mailadres uit via de bovenstaande documentatie.