Arbetsflöde för API för e-postvalidering: från sandlåda till produktion med FairValid

Arbetsflöde för API för e-postvalidering: från sandlådetest till produktionsresultat

Fråga: Du är utvecklare och lägger till e-postverifiering i ditt eget system. Vilka steg tar dig från ett första testanrop till pålitliga resultat i produktion?

Kort svar: Börja med en Test-nyckel och den kostnadsfria sandlådan. Byt sedan till en Live-nyckel som bara har de behörigheter du behöver. Skicka varje inlämning med en idempotensnyckel. Läs jobbets status och bläddra igenom resultaten. Hantera varje utfall och varje felkod separat. Stegen nedan följer FairValids API-referens för kunder.

Steg 1: Bygg mot sandlådan först

Skapa en Test-nyckel på sidan för API-nycklar och förvara den på din server. Referensen använder två miljövariabler, FAIRVALID_API_KEY och FAIRVALID_BASE_URL. Test-nycklar gör inga anrop till leverantörer och förbrukar inga krediter.

Test-nycklar accepterar endast ett litet antal reserverade adresser på domänen example.com. Dessa adresser simulerar utfallen giltig, ogiltig, catch-all, okänd, väntande och otillgänglig. Du hittar de exakta adresserna i avsnittet ”Kostnadsfri sandlåda” i API-referensen. Testjobb returnerar fasta, upprepningsbara statusar: slutförd, väntande, misslyckad eller avbruten. Massjobb i testläge stöder status, resultat och avbrytning.

Sandlådan visar dig just dessa utfall. Den täcker inte alla vägar din integration kan ta, så planera separat hantering för felkoderna som beskrivs i steg 7.

Massjobb i testläge är begränsade till 20 nya jobb per arbetsyta och timme, eller 100 per 30 dagar. Om någon av gränserna överskrids returneras HTTP 429. Ett identiskt nytt försök returnerar fortfarande det ursprungliga jobbet.

Steg 2: Gå över till en Live-nyckel med de behörigheter du behöver

För produktion skapar du en Live-nyckel med behörigheten submit. Använd POST /api/v1/jobs för batcher eller POST /api/v1/verifications för en enskild adress. Lägg till behörigheten read om nyckeln även behöver läsa jobbstatus och resultat. Live-nycklar kan också ha behörigheten balance. Separat läser GET /api/v1/balance arbetsytans tillgängliga och reserverade krediter. Den fullständiga hemligheten visas bara en gång, så förvara den säkert när du skapar nyckeln.

Live-jobb använder arbetsytans verifieringskö och kreditsaldo. Nyckelbehörigheter, nyckeltak, åtkomst till arbetsytan och bearbetningsgränser gäller fortfarande.

Steg 3: Skicka in ett jobb med en idempotensnyckel

Ett jobb accepterar 1 till 5 000 adresser i JSON, upp till 2 MiB. Skicka en Idempotency-Key-header med varje jobbinlämning och varje inlämning av en enskild adress i live-läge. Nyckeln måste vara 8 till 128 tecken lång och får innehålla bokstäver, siffror, punkter, kolon, understreck eller bindestreck.

• Ett nytt jobb returnerar HTTP 202 med ett UUID i job_id.
• Ett matchande nytt försök returnerar HTTP 200 med samma jobb.
• Att återanvända en idempotensnyckel med en ändrad body returnerar HTTP 409 idempotency_conflict.

Om du inte kan avgöra om en begäran gick igenom gör du ett nytt försök med samma API-nyckel, samma idempotensnyckel och samma normaliserade body. Återuppspelningen är knuten till API-nyckeln, så om du byter ut den autentiseringsuppgiften och skickar in igen kan en andra körning skapas. Använd en ny idempotensnyckel endast när du verkligen vill ha en ny körning, som kan debiteras.

Steg 4: Läs jobbet och bläddra igenom resultaten

Läs jobbet med GET /api/v1/jobs/{id}. Dess status kan vara köad, körs, pausad, avbryts, avbruten eller slutförd. Läs resultaten med GET /api/v1/jobs/{id}/results. Varje sida returnerar upp till 50 resultat plus en signerad next_cursor. Skicka det värdet som frågeparametern cursor. Den behåller ditt ursprungliga filter och din sökning.

Filtren är all, valid, invalid, catch_all, unknown, still_checking och not_checked. För att stoppa ett jobb begär POST /api/v1/jobs/{id}/cancel avbrytning, men arbete som redan pågår kan ändå slutföras.

Referensen beskriver också en signerad slutförandehändelse och länkar till hantering av webhooks.

Steg 5: Behandla varje utfall som en egen status

Resultatguiden förklarar vad varje resultat betyder:

• Giltig: en användbar positiv kontroll. Den garanterar aldrig leverans till inkorgen.
• Ogiltig: adressen godkändes inte.
• Catch-all: domänen kan acceptera många adresser, så en slutsats på brevlådenivå kan vara mindre säker. Läs detaljerna innan du använder den.
• Okänd: kontrollen kunde inte ge ett pålitligt svar.
• Kontrolleras fortfarande: det finns inget slutligt svar ännu.

Guiden beskriver tekniska fel och obearbetade poster separat från Okänd, och API erbjuder unknown, still_checking och not_checked som separata filter. Håll dessa statusar i separata fält eller statusar i dina egna data i stället för att slå ihop dem till Okänd.

Steg 6: Förstå kreditreservationer innan du stämmer av

API-referensen anger att arbetsytans krediter reserveras när kontroller tas in för bearbetning. Resultaten följer sedan samma regler för debitering och återföring som i instrumentpanelen. FairValids prissättning anger att en kreditreservation håller utrymme för en pågående kontroll och att det slutliga resultatet avgör debiteringen:

• Giltig eller ogiltig: 1 kredit per slutfört resultat.
• Okänd eller catch-all: inga verifieringskrediter dras i slutändan. Reserverade krediter frigörs eller återförs.
• Kontrolleras fortfarande: ingen slutlig debitering ännu. En reservation är inte en slutförd debitering.
• Tekniska fel och obearbetat arbete: inga verifieringskrediter dras i slutändan. Reservationer frigörs eller återförs.

Om du kontrollerar ditt saldo mitt under ett jobb, kom ihåg att reserverade krediter ännu inte är slutliga debiteringar. Stäm av när resultaten är slutliga. Varje konto inkluderar 300 kostnadsfria krediter per månad. De används först och förs inte över till nästa månad. Oanvända köpta krediter finns kvar så länge kontot är öppet.

Steg 7: Hantera fel utifrån orsak, inte med en enda regel för nya försök

• 401: nyckeln saknas, har återkallats eller saknar nödvändig behörighet. Åtgärda autentiseringsuppgiften eller dess behörigheter.
• 402 key_cap_reached: den nya begäran skulle överskrida nyckelns livstidstak, och inget jobb eller ingen reservation skapades. Taket räknar krediter som redan debiterats plus krediter som reserverats för accepterade unika identiteter. Eftersom det är en livstidsgräns fylls den inte på med tiden, och att vänta löser inte problemet. Be någon med behörighet att granska nyckelns takinställning. Ett tak kan inte lägga till krediter i arbetsytan.
• 422: ogiltiga adresser eller listgränser. Korrigera indata.
• 503 live_verification_unavailable: under ett driftuppehåll kan en ny inlämning i live-läge returnera detta utan att krediter reserveras. Försök igen senare med samma idempotensnyckel. Ett 503 efter en osäker inlämning bevisar inte att inget jobb skapades, så återanvänd den ursprungliga nyckeln.

Varje fel innehåller en kod, ett meddelande och ett begärande-ID. Logga alla tre så att du har dem om du kontaktar supporten.

En förnuftig arbetsordning

1. Bygg integrationen mot sandlådan och bekräfta att varje simulerat utfall hamnar där du förväntar dig.
2. Lägg till uttrycklig hantering för felkoderna ovan.
3. Skapa en Live-nyckel med så snäva behörigheter som möjligt och ett tak som passar din budget.
4. Börja med ett litet live-jobb. Jämför dess resultat och kreditstatus med instrumentpanelen och skala sedan upp.

Om du vill prova det här arbetsflödet kan du i den kostnadsfria sandlådan testa de simulerade utfallen utan att förbruka några krediter. API-referensen innehåller exakta detaljer om begärandena.