बल्क ईमेल सत्यापन API: बैच जॉब का एक व्यावहारिक वर्कफ़्लो

बल्क ईमेल सत्यापन API: बैच जॉब का एक व्यावहारिक वर्कफ़्लो

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

संक्षिप्त उत्तर: Test key के साथ सैंडबॉक्स में शुरुआत करें। फिर सूची को अधिकतम 5,000 पतों वाले जॉब में बाँटें और हर जॉब को उसकी अपनी idempotency key दें। हर जॉब को Live key से सबमिट करें, उसकी स्थिति जाँचें और परिणामों को नतीजे के अनुसार पेज-दर-पेज देखें। लंबित जाँचों, तकनीकी विफलताओं और अज्ञात परिणामों को तीन अलग-अलग स्थितियों के रूप में रखें।

साक्ष्य की जाँच 13 नवंबर 2026 को FairValid के API संदर्भ, परिणाम गाइड और क्रेडिट नियमों के आधार पर की गई।

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

API संदर्भ के अनुसार, API keys के अंतर्गत एक Test key बनाएँ, उसे अपने सर्वर पर रखें, और base URL के साथ उसे अपने environment में सेट करें। Test keys, example.com डोमेन के आरक्षित पतों के साथ काम करती हैं। वे कोई प्रदाता कॉल नहीं करतीं और कोई क्रेडिट उपयोग नहीं करतीं। Test keys अपने ही सिम्युलेटेड जॉब तक पहुँचती हैं।

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

चरण 2: सही scopes वाली Live key पर जाएँ

प्रोडक्शन के लिए, API संदर्भ के अनुसार जॉब बनाने हेतु आपको submit scope वाली Live key चाहिए। जॉब की स्थिति और परिणाम पढ़ने के लिए read scope जोड़ें। Live keys में balance scope भी हो सकता है। पूरे key secrets केवल एक बार दिखाई देते हैं, इसलिए उन्हें बनाते समय अपने सर्वर पर सुरक्षित रूप से संग्रहीत करें। रद्द (revoke) की गई key नए अनुरोध रोक देती है।

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

चरण 3: सूची बाँटें और जॉब सबमिट करें

हर जॉब JSON में 1 से 5,000 पते स्वीकार करता है, अधिकतम 2 MiB तक। यहाँ एक व्यावहारिक तरीका है:

1. अपनी सूची को हिस्सों में बाँटें। उदाहरण के लिए, 12,000 पते तीन जॉब बन जाएँगे: 5,000, 5,000 और 2,000।
2. हर हिस्से को उसकी अपनी स्थिर Idempotency-Key दें, और दर्ज करें कि आपकी कौन-सी पंक्तियाँ किस हिस्से में गईं। यह मैपिंग अपनी ओर रखने से परिणामों को अपने रिकॉर्ड से जोड़ना आसान हो जाता है।
3. jobs endpoint पर सबमिट करें। नया जॉब UUID job_id के साथ HTTP 202 लौटाता है। मेल खाता पुनः प्रयास उसी जॉब के साथ HTTP 200 लौटाता है। इसका मतलब है कि टाइमआउट के बाद आप वही अनुरोध उसी key के साथ दोबारा भेजकर मौजूदा जॉब वापस पा सकते हैं।

चरण 4: एक जैसी दिखने वाली दो त्रुटियों को संभालें

ये दोनों प्रतिक्रियाएँ सबमिशन रोक सकती हैं, लेकिन इनका अर्थ अलग है:

• HTTP 503 live_verification_unavailable किसी परिचालन विराम के दौरान आ सकता है। API संदर्भ के अनुसार, ऐसा क्रेडिट होल्ड किए बिना होता है। बाद में उसी Idempotency-Key के साथ पुनः प्रयास करें।
• HTTP 402 key_cap_reached का अर्थ है कि नया अनुरोध key की आजीवन खर्च सीमा पार कर जाएगा। इस सीमा में पहले से चार्ज किए गए क्रेडिट और स्वीकृत अद्वितीय पहचानों के लिए आरक्षित क्रेडिट गिने जाते हैं। कोई जॉब या होल्ड नहीं बनता। आजीवन सीमा समय के साथ फिर से नहीं भरती, इसलिए इंतज़ार करने से यह ठीक नहीं होगा। API key सेटिंग्स में key की सीमा की समीक्षा करें, या ऐसी key उपयोग करें जिसमें काम के लिए पर्याप्त शेष सीमा हो। key सीमा वर्कस्पेस में क्रेडिट भी नहीं जोड़ सकती। यह केवल यह सीमित करती है कि वह key कितना खर्च कर सकती है।

इन दोनों प्रतिक्रियाओं को अनुमति त्रुटियों और प्रोसेसिंग सीमाओं से अलग लॉग करें, ताकि सही व्यक्ति को सही अलर्ट मिले।

चरण 5: जॉब की स्थिति ट्रैक करें, फिर परिणाम पेज-दर-पेज पढ़ें

job endpoint जॉब की वर्तमान स्थिति और सारांश लौटाता है। जॉब की स्थिति कतार में, चल रहा, रुका हुआ, रद्द हो रहा, रद्द या पूर्ण हो सकती है। यदि आप रद्द करने का अनुरोध करते हैं, तो पहले से चल रहा काम फिर भी पूरा हो सकता है।

results endpoint एक बार में अधिकतम 50 परिणाम लौटाता है, साथ में एक हस्ताक्षरित next_cursor भी। उस मान को cursor query parameter के रूप में भेजें। यह आपका मूल फ़िल्टर और खोज आगे ले जाता है। फ़िल्टर हैं all, valid, invalid, catch_all, unknown, still_checking और not_checked। इनसे आप केवल वे पंक्तियाँ निकाल सकते हैं जिन पर निर्णय लेना है, जैसे unknown चिह्नित सब कुछ।

चरण 6: नतीजों को निर्णयों में बदलें

परिणाम गाइड परिणामों को साक्ष्य के रूप में बताती है, डिलीवरी की गारंटी के रूप में नहीं:

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

तकनीकी विफलताएँ और अप्रसंस्कृत आइटम एक अलग श्रेणी हैं। FairValid के क्रेडिट नियमों के अनुसार उन्हें अज्ञात के रूप में दोबारा चिह्नित नहीं किया जाता।

चरण 7: क्रेडिट आरक्षण को समझें

API संदर्भ के अनुसार, जैसे-जैसे जाँचें प्रोसेसिंग के लिए स्वीकार की जाती हैं, वर्कस्पेस क्रेडिट आरक्षित किए जाते हैं। परिणाम डैशबोर्ड जैसे ही चार्जिंग और वापसी नियमों का पालन करते हैं। क्रेडिट नियमों के तहत, पूर्ण वैध या अवैध परिणाम पर एक क्रेडिट लगता है। अज्ञात और अनसुलझे कैच-ऑल परिणामों पर अंततः कोई सत्यापन क्रेडिट नहीं कटता, क्योंकि होल्ड किए गए क्रेडिट मुक्त कर दिए जाते हैं या लौटा दिए जाते हैं। लंबित कोई अंतिम परिणाम नहीं है। तकनीकी विफलताओं और अप्रसंस्कृत काम पर भी अंततः कोई क्रेडिट नहीं कटता। लौटाए गए क्रेडिट अपने मूल लॉट और समाप्ति नियम बनाए रखते हैं।

balance endpoint लाइव वर्कस्पेस के उपलब्ध और होल्ड किए गए क्रेडिट बताता है। जब उसका free_allowance_held फ़ील्ड true होता है, तो मुफ़्त भत्ता होल्ड पर होता है और available_credits या free_available में नहीं गिना जाता। सशुल्क क्रेडिट उपलब्ध रहते हैं। मूल खाते को हर महीने उसकी साइनअप तिथि पर 300 मुफ़्त क्रेडिट मिलते हैं, और अप्रयुक्त मुफ़्त क्रेडिट अगले महीने में आगे नहीं जाते। अतिरिक्त वर्कस्पेस को अलग से मुफ़्त भत्ता नहीं मिलता। मुफ़्त क्रेडिट पहले उपयोग होते हैं, और खाता खुला रहने तक सशुल्क क्रेडिट समाप्त नहीं होते।

एक सरल चेकलिस्ट

• Test key और प्रलेखित सैंडबॉक्स केसों से परीक्षण करें।
• submit और read scopes वाली Live key उपयोग करें, जिसकी सीमा नियोजित काम के अनुरूप हो।
• हर हिस्से को 5,000 या उससे कम पतों तक रखें, हर हिस्से के लिए एक स्थिर idempotency key के साथ।
• 503 आने पर बाद में उसी key से पुनः प्रयास करें। 402 आने पर इंतज़ार न करें; उसके बजाय सीमा का समाधान करें।
• हस्ताक्षरित cursor से, नतीजे के अनुसार फ़िल्टर करके, परिणाम पेज-दर-पेज देखें।
• अपने डेटा में लंबित, तकनीकी विफलता और अज्ञात को अलग रखें।

यदि आप यह वर्कफ़्लो आज़माना चाहते हैं, तो अपने पहले लाइव सबमिशन से पहले आप Test key बनाकर बिना क्रेडिट उपयोग किए सैंडबॉक्स जॉब चला सकते हैं। endpoint का पूरा विवरण API संदर्भ में है।