ईमेल वैलिडेशन API वर्कफ़्लो: FairValid के साथ सैंडबॉक्स से प्रोडक्शन तक

ईमेल वैलिडेशन API वर्कफ़्लो: सैंडबॉक्स टेस्ट से प्रोडक्शन परिणामों तक

प्रश्न: आप एक डेवलपर हैं और अपने सिस्टम में ईमेल सत्यापन जोड़ रहे हैं। पहली टेस्ट कॉल से भरोसेमंद प्रोडक्शन परिणामों तक पहुँचने के लिए कौन-से चरण ज़रूरी हैं?

संक्षिप्त उत्तर: Test कुंजी और मुफ़्त सैंडबॉक्स से शुरुआत करें। फिर ऐसी Live कुंजी पर जाएँ जिसमें केवल ज़रूरी स्कोप हों। हर सबमिशन आइडेम्पोटेंसी कुंजी के साथ भेजें। जॉब की स्थिति पढ़ें और परिणामों को पेज-दर-पेज देखें। हर परिणाम और हर त्रुटि कोड को अलग-अलग संभालें। नीचे दिए गए चरण FairValid ग्राहक API संदर्भ पर आधारित हैं।

चरण 1: पहले सैंडबॉक्स पर बनाएँ

API कुंजी पेज पर एक Test कुंजी बनाएँ और उसे अपने सर्वर पर रखें। संदर्भ में दो एनवायरनमेंट वेरिएबल इस्तेमाल होते हैं, FAIRVALID_API_KEY और FAIRVALID_BASE_URL। Test कुंजियाँ किसी प्रोवाइडर को कॉल नहीं करतीं और कोई क्रेडिट इस्तेमाल नहीं करतीं।

Test कुंजियाँ example.com डोमेन पर केवल कुछ आरक्षित पतों को ही स्वीकार करती हैं। ये पते वैध, अवैध, कैच-ऑल, अज्ञात, लंबित और अनुपलब्ध परिणामों का अनुकरण करते हैं। सटीक पते आपको API संदर्भ के "मुफ़्त सैंडबॉक्स" अनुभाग में मिलेंगे। टेस्ट जॉब तय और दोहराने योग्य स्थितियाँ लौटाते हैं: पूर्ण, लंबित, विफल या रद्द। बल्क टेस्ट जॉब स्थिति, परिणाम और रद्दीकरण को सपोर्ट करते हैं।

सैंडबॉक्स आपको केवल ये विशिष्ट परिणाम दिखाता है। यह आपके इंटीग्रेशन के हर संभावित रास्ते को कवर नहीं करता, इसलिए चरण 7 में बताए गए त्रुटि कोड के लिए अलग से हैंडलिंग की योजना बनाएँ।

बल्क टेस्ट जॉब प्रति वर्कस्पेस प्रति घंटे 20 नए जॉब, या प्रति 30 दिन 100 जॉब तक सीमित हैं। इनमें से कोई भी सीमा पार करने पर HTTP 429 लौटता है। समान रीट्राई फिर भी मूल जॉब ही लौटाता है।

चरण 2: ज़रूरी स्कोप वाली Live कुंजी पर जाएँ

प्रोडक्शन के लिए submit स्कोप वाली Live कुंजी बनाएँ। बैच के लिए POST /api/v1/jobs या एक पते के लिए POST /api/v1/verifications का उपयोग करें। अगर कुंजी को जॉब की स्थिति और परिणाम भी पढ़ने हों, तो read स्कोप जोड़ें। Live कुंजियों में balance स्कोप भी हो सकता है। अलग से, GET /api/v1/balance वर्कस्पेस के उपलब्ध और होल्ड किए गए क्रेडिट पढ़ता है। पूरा सीक्रेट केवल एक बार दिखाया जाता है, इसलिए कुंजी बनाते समय ही उसे सुरक्षित रूप से सहेज लें।

Live जॉब आपके वर्कस्पेस की सत्यापन कतार और क्रेडिट बैलेंस का उपयोग करते हैं। कुंजी स्कोप, कुंजी कैप, वर्कस्पेस एक्सेस और प्रोसेसिंग सीमाएँ सभी लागू रहती हैं।

चरण 3: आइडेम्पोटेंसी कुंजी के साथ जॉब सबमिट करें

एक जॉब JSON में 1 से 5,000 पते तक स्वीकार करता है, अधिकतम 2 MiB तक। हर जॉब सबमिशन और हर लाइव एकल-पता सबमिशन के साथ Idempotency-Key हेडर भेजें। कुंजी 8 से 128 अक्षर लंबी होनी चाहिए और इसमें अक्षर, अंक, डॉट, कोलन, अंडरस्कोर या हाइफ़न हो सकते हैं।

• नया जॉब UUID job_id के साथ HTTP 202 लौटाता है।
• मेल खाता रीट्राई उसी जॉब के साथ HTTP 200 लौटाता है।
• बदली हुई बॉडी के साथ आइडेम्पोटेंसी कुंजी दोबारा इस्तेमाल करने पर HTTP 409 idempotency_conflict लौटता है।

अगर आप तय नहीं कर पा रहे कि अनुरोध पहुँचा या नहीं, तो उसी API कुंजी, उसी आइडेम्पोटेंसी कुंजी और उसी नॉर्मलाइज़्ड बॉडी के साथ रीट्राई करें। रीप्ले API कुंजी तक सीमित है, इसलिए वह क्रेडेंशियल बदलकर दोबारा सबमिट करने से दूसरा रन बन सकता है। नई आइडेम्पोटेंसी कुंजी तभी इस्तेमाल करें जब आप वाकई नया रन चाहते हों, जिसके लिए शुल्क लग सकता है।

चरण 4: जॉब पढ़ें और परिणामों को पेज-दर-पेज देखें

GET /api/v1/jobs/{id} से जॉब पढ़ें। उसकी स्थिति queued, running, paused, canceling, canceled या completed हो सकती है। GET /api/v1/jobs/{id}/results से परिणाम पढ़ें। हर पेज अधिकतम 50 परिणाम और एक हस्ताक्षरित next_cursor लौटाता है। उस मान को cursor क्वेरी पैरामीटर के रूप में भेजें। यह आपका मूल फ़िल्टर और खोज बनाए रखता है।

फ़िल्टर हैं: all, valid, invalid, catch_all, unknown, still_checking और not_checked। जॉब रोकने के लिए POST /api/v1/jobs/{id}/cancel रद्दीकरण का अनुरोध करता है, लेकिन पहले से चल रहा काम फिर भी पूरा हो सकता है।

संदर्भ में एक हस्ताक्षरित पूर्णता इवेंट का भी वर्णन है और वेबहुक प्रबंधन का लिंक भी दिया गया है।

चरण 5: हर परिणाम को उसकी अपनी स्थिति मानें

परिणाम गाइड बताती है कि हर परिणाम का क्या अर्थ है:

• वैध: उपयोग योग्य सकारात्मक जाँच। यह कभी भी इनबॉक्स डिलीवरी की गारंटी नहीं देता।
• अवैध: पता जाँच में पास नहीं हुआ।
• कैच-ऑल: डोमेन कई पते स्वीकार कर सकता है, इसलिए मेलबॉक्स-स्तर का निष्कर्ष कम निश्चित हो सकता है। उपयोग करने से पहले विवरण पढ़ें।
• अज्ञात: जाँच कोई भरोसेमंद उत्तर नहीं दे सकी।
• अभी जाँच जारी है: अभी तक कोई अंतिम उत्तर नहीं है।

गाइड तकनीकी विफलताओं और अप्रोसेस्ड आइटम को अज्ञात से अलग बताती है, और API unknown, still_checking और not_checked को अलग-अलग फ़िल्टर के रूप में देता है। इन स्थितियों को अज्ञात में मिलाने के बजाय अपने डेटा में अलग फ़ील्ड या स्टेटस में रखें।

चरण 6: मिलान से पहले क्रेडिट होल्ड को समझें

API संदर्भ के अनुसार, जैसे-जैसे जाँचें प्रोसेसिंग के लिए स्वीकार की जाती हैं, वर्कस्पेस क्रेडिट आरक्षित किए जाते हैं। इसके बाद परिणामों पर वही शुल्क और वापसी नियम लागू होते हैं जो डैशबोर्ड पर होते हैं। FairValid प्राइसिंग के अनुसार, क्रेडिट होल्ड चल रही जाँच के लिए जगह सुरक्षित रखता है, और अंतिम परिणाम शुल्क तय करता है:

• वैध या अवैध: प्रति पूर्ण परिणाम 1 क्रेडिट।
• अज्ञात या कैच-ऑल: अंततः कोई सत्यापन क्रेडिट नहीं कटता। होल्ड किए गए क्रेडिट मुक्त कर दिए जाते हैं या वापस कर दिए जाते हैं।
• अभी जाँच जारी है: अभी कोई अंतिम शुल्क नहीं। होल्ड कोई पूर्ण शुल्क नहीं है।
• तकनीकी विफलताएँ और अप्रोसेस्ड काम: अंततः कोई सत्यापन क्रेडिट नहीं कटता। आरक्षित क्रेडिट मुक्त कर दिए जाते हैं या वापस कर दिए जाते हैं।

अगर आप जॉब के बीच में अपना बैलेंस देखते हैं, तो याद रखें कि होल्ड किए गए क्रेडिट अभी अंतिम शुल्क नहीं हैं। परिणाम अंतिम होने के बाद मिलान करें। हर खाते में हर महीने 300 मुफ़्त क्रेडिट शामिल होते हैं। इनका उपयोग पहले होता है और ये अगले महीने में आगे नहीं जुड़ते। भुगतान किए गए अप्रयुक्त क्रेडिट तब तक आगे उपलब्ध रहते हैं जब तक खाता खुला रहता है।

चरण 7: त्रुटियों को एक ही रीट्राई नियम से नहीं, उनके कारण के अनुसार संभालें

• 401: कुंजी मौजूद नहीं है, रद्द कर दी गई है या उसमें ज़रूरी स्कोप नहीं है। क्रेडेंशियल या उसके स्कोप ठीक करें।
• 402 key_cap_reached: नया अनुरोध कुंजी की आजीवन कैप से अधिक हो जाएगा, और कोई जॉब या होल्ड नहीं बनाया गया। कैप में पहले से कटे क्रेडिट और स्वीकृत यूनिक पहचानों के लिए आरक्षित क्रेडिट दोनों गिने जाते हैं। चूँकि यह आजीवन सीमा है, यह समय के साथ फिर से नहीं भरती और इंतज़ार करने से हटती नहीं। एक्सेस वाले किसी व्यक्ति से उस कुंजी की कैप सेटिंग की समीक्षा करवाएँ। कैप वर्कस्पेस में क्रेडिट नहीं जोड़ सकती।
• 422: अमान्य पते या सूची की सीमाएँ। इनपुट ठीक करें।
• 503 live_verification_unavailable: परिचालन विराम के दौरान, नया लाइव सबमिशन क्रेडिट होल्ड किए बिना यह लौटा सकता है। बाद में उसी आइडेम्पोटेंसी कुंजी के साथ रीट्राई करें। अनिश्चित सबमिशन के बाद आया 503 यह साबित नहीं करता कि कोई जॉब नहीं बना, इसलिए मूल कुंजी ही दोबारा इस्तेमाल करें।

हर त्रुटि में एक कोड, एक संदेश और एक अनुरोध ID होती है। तीनों को लॉग करें ताकि सपोर्ट से संपर्क करते समय ये आपके पास हों।

काम का एक समझदार क्रम

1. इंटीग्रेशन को सैंडबॉक्स पर बनाएँ और पुष्टि करें कि हर अनुकरित परिणाम वहीं पहुँचता है जहाँ आप उम्मीद करते हैं।
2. ऊपर बताए गए त्रुटि कोड के लिए स्पष्ट हैंडलिंग जोड़ें।
3. सबसे सीमित ज़रूरी स्कोप और आपके बजट के अनुरूप कैप वाली Live कुंजी बनाएँ।
4. एक छोटे लाइव जॉब से शुरुआत करें। उसके परिणामों और क्रेडिट स्थितियों की डैशबोर्ड से तुलना करें, फिर दायरा बढ़ाएँ।

अगर आप यह वर्कफ़्लो आज़माना चाहते हैं, तो मुफ़्त सैंडबॉक्स आपको बिना कोई क्रेडिट खर्च किए अनुकरित परिणामों को टेस्ट करने देता है। सटीक अनुरोध विवरण API संदर्भ में दिए गए हैं।