Massverifiering av e-postadresser via API: ett praktiskt arbetsflöde för batchjobb

Massverifiering av e-postadresser via API: ett praktiskt arbetsflöde för batchjobb

Frågan: Du har en stor lista med adresser i ditt eget system. Hur skickar du den genom FairValid API i omgångar, hanterar fel på ett säkert sätt och läser tillbaka resultaten utan att tappa kontrollen över krediterna?

Kort svar: Börja i sandlådan med en testnyckel. Dela sedan upp listan i jobb med upp till 5 000 adresser och ge varje jobb en egen idempotensnyckel. Skicka in varje jobb med en livenyckel, kontrollera dess status och bläddra igenom resultaten per utfall. Håll väntande kontroller, tekniska fel och Okänt-resultat isär som tre separata situationer.

Underlaget kontrollerades 13 november 2026 mot FairValid:s API-referens, resultatguide och kreditregler.

Steg 1: Bygg först mot sandlådan

Enligt API-referensen ska du skapa en testnyckel under API-nycklar, behålla den på din server och ange den i din miljö tillsammans med bas-URL:en. Testnycklar fungerar med reserverade adresser på domänen example.com. De gör inga anrop till leverantörer och förbrukar inga krediter. Testnycklar har åtkomst till sina egna simulerade jobb.

Testjobb returnerar deterministiska tillstånd: slutfört, väntande, misslyckat eller avbrutet. Se API-referensen för de exakta sandlådeadresserna och använd dem för att bekräfta att din kod hanterar dessa tillstånd. Fallen visar bara de utfall de är utformade för. De täcker inte alla grenar i din integration, så granska dina egna felvägar separat.

Steg 2: Gå över till en livenyckel med rätt behörigheter

För produktion behöver du enligt API-referensen en livenyckel med behörigheten submit för att skapa jobb. Lägg till behörigheten read för att läsa jobbstatus och resultat. Livenycklar kan även ha behörigheten balance. Fullständiga nyckelhemligheter visas bara en gång, så lagra dem säkert på din server när du skapar dem. En återkallad nyckel stoppar nya förfrågningar.

Livejobb använder arbetsytans verifieringskö och kreditsaldo. Nyckelbehörigheter, nyckeltak, åtkomst till arbetsytan och bearbetningsgränser gäller fortfarande. En livenyckel ger dig inte obegränsad åtkomst.

Steg 3: Dela upp listan och skicka in jobb

Varje jobb tar emot 1 till 5 000 adresser i JSON, upp till 2 MiB. Så här kan du göra i praktiken:

1. Dela upp listan. Som exempel skulle 12 000 adresser bli tre jobb med 5 000, 5 000 och 2 000.
2. Ge varje del en egen stabil Idempotency-Key och notera vilka av dina rader som hamnade i vilken del. Om du sparar den kopplingen hos dig blir det enklare att matcha resultaten mot dina poster.
3. Skicka till jobbslutpunkten. Ett nytt jobb returnerar HTTP 202 med ett UUID som job_id. Ett matchande nytt försök returnerar HTTP 200 med samma jobb. Det innebär att du efter en timeout kan skicka samma förfrågan igen med samma nyckel och få tillbaka det befintliga jobbet.

Steg 4: Hantera de två felen som liknar varandra

Båda dessa svar kan blockera en inskickning, men de betyder olika saker:

• HTTP 503 live_verification_unavailable kan returneras under ett driftuppehåll. Enligt API-referensen sker detta utan att krediter reserveras. Försök igen senare med samma Idempotency-Key.
• HTTP 402 key_cap_reached betyder att en ny förfrågan skulle överskrida nyckelns livstidstak för förbrukning. Taket räknar krediter som redan debiterats plus krediter som reserverats för accepterade unika identiteter. Inget jobb och ingen reservation skapas. Ett livstidstak fylls inte på med tiden, så det hjälper inte att vänta. Se över nyckelns tak i inställningarna för API-nycklar, eller använd en nyckel med tillräckligt återstående tak för arbetet. Ett nyckeltak kan inte heller lägga till krediter i arbetsytan. Det begränsar bara vad nyckeln får förbruka.

Logga dessa två svar separat från behörighetsfel och bearbetningsgränser, så att rätt person får rätt larm.

Steg 5: Följ jobbets status och bläddra sedan igenom resultaten

Jobbslutpunkten returnerar jobbets aktuella status och sammanfattning. Jobbstatus kan vara köad, körs, pausad, avbryts, avbruten eller slutförd. Om du begär avbrytande kan arbete som redan pågår ändå slutföras.

Resultatslutpunkten returnerar upp till 50 resultat åt gången, tillsammans med en signerad next_cursor. Skicka det värdet som frågeparametern cursor. Det för med sig ditt ursprungliga filter och din sökning. Filtren är all, valid, invalid, catch_all, unknown, still_checking och not_checked. Du kan använda dem för att bara hämta de rader som kräver ett beslut, till exempel allt som markerats som unknown.

Steg 6: Omvandla utfall till beslut

Resultatguiden beskriver resultat som underlag, inte som en leveransgaranti:

• Giltig anger en användbar positiv kontroll. Det garanterar aldrig leverans till inkorgen.
• Ogiltig betyder att adressen inte godkändes.
• Catch-all betyder att domänen kan ta emot många adresser, så en slutsats om den specifika brevlådan kan vara mindre säker. Läs detaljerna innan du använder adressen.
• Okänt betyder att kontrollen inte kunde ge ett tillförlitligt svar.
• Kontrolleras fortfarande betyder att det ännu inte finns något slutligt svar. Fortsätt att fråga efter status och behandla det inte som Okänt.

Tekniska fel och obearbetade poster är en separat kategori. Enligt FairValid:s kreditregler märks de inte om som Okänt.

Steg 7: Förstå kreditreservationer

Enligt API-referensen reserveras arbetsytans krediter när kontroller tas in för bearbetning. Resultaten följer samma regler för debitering och återföring som i instrumentpanelen. Enligt kreditreglerna kostar ett slutfört Giltig- eller Ogiltig-resultat en kredit. För Okänt och olösta Catch-all-resultat dras i slutänden inga verifieringskrediter, eftersom reserverade krediter frigörs eller återförs. Väntande är inget slutligt resultat. För tekniska fel och obearbetat arbete dras inte heller några krediter i slutänden. Återförda krediter behåller den post och de utgångsregler de ursprungligen hade.

Saldoslutpunkten rapporterar tillgängliga och reserverade krediter för den aktiva arbetsytan. När fältet free_allowance_held är true är den kostnadsfria tilldelningen spärrad och räknas inte in i available_credits eller free_available. Betalda krediter förblir tillgängliga. Det ursprungliga kontot får 300 kostnadsfria krediter varje månad på registreringsdagen, och oanvända kostnadsfria krediter förs inte över. Ytterligare arbetsytor får ingen extra kostnadsfri tilldelning. Kostnadsfria krediter används först, och betalda krediter upphör inte att gälla så länge kontot är öppet.

En enkel checklista

• Testa med en testnyckel och de dokumenterade sandlådefallen.
• Använd en livenyckel med behörigheterna submit och read, och ett tak som passar det planerade arbetet.
• Håll varje del till högst 5 000 adresser, med en egen stabil idempotensnyckel per del.
• Försök igen senare med samma nyckel vid 503. Vänta inte ut ett 402; åtgärda taket i stället.
• Bläddra igenom resultaten med den signerade markören, filtrerade per utfall.
• Håll väntande, tekniska fel och Okänt isär i dina data.

Om du vill prova det här arbetsflödet kan du skapa en testnyckel och köra ett sandlådejobb utan att förbruka krediter innan din första liveinskickning. API-referensen innehåller fullständig information om slutpunkterna.