ইমেইল যাচাই API ওয়ার্কফ্লো: FairValid-এর সাথে স্যান্ডবক্স থেকে প্রোডাকশন পর্যন্ত

ইমেইল যাচাই API ওয়ার্কফ্লো: স্যান্ডবক্স পরীক্ষা থেকে প্রোডাকশন ফলাফল পর্যন্ত

প্রশ্ন: আপনি একজন ডেভেলপার এবং নিজের সিস্টেমে ইমেইল যাচাই যুক্ত করছেন। প্রথম পরীক্ষামূলক কল থেকে নির্ভরযোগ্য প্রোডাকশন ফলাফল পর্যন্ত কোন ধাপগুলো অনুসরণ করবেন?

সংক্ষিপ্ত উত্তর: একটি Test কী ও বিনামূল্যের স্যান্ডবক্স দিয়ে শুরু করুন। এরপর শুধু প্রয়োজনীয় স্কোপসহ একটি Live কী-তে যান। প্রতিটি জমা একটি idempotency কী দিয়ে পাঠান। জবের অবস্থা পড়ুন এবং পেজ ধরে ফলাফল দেখুন। প্রতিটি ফলাফল ও প্রতিটি ত্রুটি কোড আলাদাভাবে সামলান। নিচের ধাপগুলো FairValid-এর গ্রাহক API রেফারেন্স অনুসরণ করে।

ধাপ ১: প্রথমে স্যান্ডবক্সে তৈরি করুন

API কী পেজে একটি Test কী তৈরি করুন এবং সেটি আপনার সার্ভারে রাখুন। রেফারেন্সে দুটি এনভায়রনমেন্ট ভেরিয়েবল ব্যবহার করা হয়েছে, FAIRVALID_API_KEY ও FAIRVALID_BASE_URL। Test কী কোনো প্রোভাইডার কল করে না এবং কোনো ক্রেডিট ব্যবহার করে না।

Test কী শুধু example.com ডোমেইনের অল্প কিছু সংরক্ষিত ঠিকানা গ্রহণ করে। এসব ঠিকানা বৈধ, অবৈধ, ক্যাচ-অল, অজানা, অপেক্ষমাণ ও অনুপলব্ধ ফলাফলের অনুকরণ করে। সঠিক ঠিকানাগুলো পাবেন API রেফারেন্সের "বিনামূল্যের স্যান্ডবক্স" অংশে। টেস্ট জব নির্দিষ্ট ও পুনরাবৃত্তিযোগ্য অবস্থা ফেরত দেয়: সম্পন্ন, অপেক্ষমাণ, ব্যর্থ বা বাতিল। বাল্ক টেস্ট জবে স্ট্যাটাস, ফলাফল ও বাতিলকরণ সমর্থিত।

স্যান্ডবক্স আপনাকে ওই নির্দিষ্ট ফলাফলগুলো দেখায়। আপনার ইন্টিগ্রেশনের সম্ভাব্য সব পথ এতে থাকে না, তাই ধাপ ৭-এ বর্ণিত ত্রুটি কোডগুলোর জন্য আলাদা ব্যবস্থা পরিকল্পনা করুন।

বাল্ক টেস্ট জব প্রতি ওয়ার্কস্পেসে প্রতি ঘণ্টায় ২০টি নতুন জব, অথবা ৩০ দিনে ১০০টিতে সীমিত। যেকোনো সীমা পার হলে HTTP ৪২৯ ফেরত আসে। হুবহু একই পুনঃচেষ্টা তবুও মূল জবটিই ফেরত দেয়।

ধাপ ২: প্রয়োজনীয় স্কোপসহ একটি Live কী-তে যান

প্রোডাকশনের জন্য submit স্কোপসহ একটি Live কী তৈরি করুন। ব্যাচের জন্য POST /api/v1/jobs অথবা একটি ঠিকানার জন্য POST /api/v1/verifications ব্যবহার করুন। কী-টির যদি জবের অবস্থা ও ফলাফলও পড়তে হয়, তাহলে read স্কোপ যোগ করুন। Live কী-তে balance স্কোপও থাকতে পারে। আলাদাভাবে, GET /api/v1/balance ওয়ার্কস্পেসের উপলব্ধ ও হোল্ড করা ক্রেডিট পড়ে। সম্পূর্ণ সিক্রেট শুধু একবারই দেখানো হয়, তাই কী তৈরির সময় এটি নিরাপদে সংরক্ষণ করুন।

Live জব আপনার ওয়ার্কস্পেসের যাচাই কিউ ও ক্রেডিট ব্যালান্স ব্যবহার করে। কী স্কোপ, কী ক্যাপ, ওয়ার্কস্পেস অ্যাক্সেস ও প্রসেসিং সীমা সবই তখনও প্রযোজ্য।

ধাপ ৩: একটি idempotency কী দিয়ে জব জমা দিন

একটি জব JSON-এ ১ থেকে ৫,০০০টি ঠিকানা গ্রহণ করে, সর্বোচ্চ ২ MiB পর্যন্ত। প্রতিটি জব জমা এবং প্রতিটি লাইভ একক-ঠিকানা জমার সাথে একটি Idempotency-Key হেডার পাঠান। কী-টির দৈর্ঘ্য ৮ থেকে ১২৮ অক্ষর হতে হবে এবং এতে অক্ষর, অঙ্ক, ডট, কোলন, আন্ডারস্কোর বা হাইফেন ব্যবহার করা যায়।

• নতুন জব একটি UUID job_id-সহ HTTP ২০২ ফেরত দেয়।
• মিলে যাওয়া পুনঃচেষ্টা একই জবসহ HTTP ২০০ ফেরত দেয়।
• পরিবর্তিত বডিসহ একটি idempotency কী পুনরায় ব্যবহার করলে HTTP ৪০৯ idempotency_conflict ফেরত আসে।

কোনো রিকোয়েস্ট পৌঁছেছে কি না বুঝতে না পারলে একই API কী, একই idempotency কী ও একই নর্মালাইজড বডি দিয়ে আবার চেষ্টা করুন। রিপ্লে API কী-এর মধ্যে সীমাবদ্ধ, তাই সেই ক্রেডেনশিয়াল বদলে আবার জমা দিলে দ্বিতীয় একটি রান তৈরি হতে পারে। শুধু তখনই নতুন idempotency কী ব্যবহার করুন যখন সত্যিই একটি নতুন রান চান, যার জন্য চার্জ হতে পারে।

ধাপ ৪: জব পড়ুন এবং পেজ ধরে ফলাফল দেখুন

GET /api/v1/jobs/{id} দিয়ে জব পড়ুন। এর স্ট্যাটাস হতে পারে কিউতে, চলমান, বিরতিতে, বাতিল হচ্ছে, বাতিল বা সম্পন্ন। GET /api/v1/jobs/{id}/results দিয়ে ফলাফল পড়ুন। প্রতিটি পেজ সর্বোচ্চ ৫০টি ফলাফল এবং একটি স্বাক্ষরিত next_cursor ফেরত দেয়। সেই মানটি cursor কোয়েরি প্যারামিটার হিসেবে পাঠান। এটি আপনার মূল ফিল্টার ও সার্চ বজায় রাখে।

ফিল্টারগুলো হলো all, valid, invalid, catch_all, unknown, still_checking ও not_checked। কোনো জব থামাতে POST /api/v1/jobs/{id}/cancel বাতিলের অনুরোধ করে, তবে ইতিমধ্যে চলমান কাজ তবুও শেষ হতে পারে।

রেফারেন্সে একটি স্বাক্ষরিত সমাপ্তি ইভেন্টের বর্ণনাও আছে এবং ওয়েবহুক ব্যবস্থাপনার লিংক দেওয়া আছে।

ধাপ ৫: প্রতিটি ফলাফলকে আলাদা অবস্থা হিসেবে বিবেচনা করুন

ফলাফল নির্দেশিকা প্রতিটি ফলাফলের অর্থ ব্যাখ্যা করে:

• বৈধ: একটি ব্যবহারযোগ্য ইতিবাচক যাচাই। এটি কখনোই ইনবক্সে পৌঁছানোর নিশ্চয়তা দেয় না।
• অবৈধ: ঠিকানাটি যাচাইয়ে উত্তীর্ণ হয়নি।
• ক্যাচ-অল: ডোমেইনটি অনেক ঠিকানা গ্রহণ করতে পারে, তাই মেইলবক্স-স্তরের সিদ্ধান্ত কম নিশ্চিত হতে পারে। ব্যবহারের আগে বিস্তারিত পড়ুন।
• অজানা: যাচাইটি নির্ভরযোগ্য উত্তর দিতে পারেনি।
• এখনও যাচাই চলছে: এখনও কোনো চূড়ান্ত উত্তর নেই।

নির্দেশিকাটি প্রযুক্তিগত ব্যর্থতা ও অপ্রক্রিয়াকৃত আইটেমকে অজানা থেকে আলাদাভাবে বর্ণনা করে, এবং API unknown, still_checking ও not_checked-কে আলাদা ফিল্টার হিসেবে দেয়। এই অবস্থাগুলো অজানা-র সাথে মিশিয়ে না ফেলে আপনার নিজের ডেটায় আলাদা ফিল্ড বা স্ট্যাটাসে রাখুন।

ধাপ ৬: মিলিয়ে দেখার আগে ক্রেডিট হোল্ড বুঝে নিন

API রেফারেন্স অনুযায়ী, যাচাইগুলো প্রসেসিংয়ের জন্য গৃহীত হওয়ার সাথে সাথে ওয়ার্কস্পেসের ক্রেডিট সংরক্ষিত হয়। এরপর ফলাফলগুলো ড্যাশবোর্ডের মতোই চার্জ ও ফেরতের নিয়ম অনুসরণ করে। FairValid-এর মূল্য নির্ধারণ অনুযায়ী, ক্রেডিট হোল্ড একটি চলমান যাচাইয়ের জন্য জায়গা রাখে, এবং চূড়ান্ত ফলাফলই চার্জ নির্ধারণ করে:

• বৈধ বা অবৈধ: প্রতিটি সম্পন্ন ফলাফলের জন্য ১ ক্রেডিট।
• অজানা বা ক্যাচ-অল: শেষ পর্যন্ত কোনো যাচাই ক্রেডিট কাটা হয় না। হোল্ড করা ক্রেডিট মুক্ত করা হয় বা ক্রেডিট হিসেবে ফেরত দেওয়া হয়।
• এখনও যাচাই চলছে: এখনও কোনো চূড়ান্ত চার্জ নেই। হোল্ড মানে সম্পন্ন চার্জ নয়।
• প্রযুক্তিগত ব্যর্থতা ও অপ্রক্রিয়াকৃত কাজ: শেষ পর্যন্ত কোনো যাচাই ক্রেডিট কাটা হয় না। সংরক্ষিত ক্রেডিট মুক্ত করা হয় বা ফেরত দেওয়া হয়।

জব চলার মাঝপথে ব্যালান্স দেখলে মনে রাখবেন, হোল্ড করা ক্রেডিট এখনও চূড়ান্ত চার্জ নয়। ফলাফল চূড়ান্ত হওয়ার পরে মিলিয়ে দেখুন। প্রতিটি অ্যাকাউন্টে প্রতি মাসে ৩০০টি বিনামূল্যের ক্রেডিট থাকে। এগুলো প্রথমে ব্যবহৃত হয় এবং পরের মাসে যোগ হয় না। অ্যাকাউন্ট খোলা থাকা পর্যন্ত কেনা ক্রেডিটের অব্যবহৃত অংশ পরবর্তী সময়েও ব্যবহারযোগ্য থাকে।

ধাপ ৭: একটিমাত্র পুনঃচেষ্টার নিয়মে নয়, কারণ অনুযায়ী ত্রুটি সামলান

• ৪০১: কী অনুপস্থিত, বাতিল করা হয়েছে বা প্রয়োজনীয় স্কোপ নেই। ক্রেডেনশিয়াল বা এর স্কোপ ঠিক করুন।
• ৪০২ key_cap_reached: নতুন রিকোয়েস্টটি কী-এর আজীবন ক্যাপ ছাড়িয়ে যেত, এবং কোনো জব বা হোল্ড তৈরি হয়নি। ক্যাপে গণনা করা হয় ইতিমধ্যে চার্জ হওয়া ক্রেডিট এবং গৃহীত স্বতন্ত্র আইডেন্টিটির জন্য সংরক্ষিত ক্রেডিট। যেহেতু এটি আজীবন সীমা, সময়ের সাথে এটি পূরণ হয় না এবং অপেক্ষা করলেও এটি দূর হবে না। অ্যাক্সেস আছে এমন কাউকে দিয়ে ওই কী-এর ক্যাপ সেটিং পর্যালোচনা করান। ক্যাপ ওয়ার্কস্পেসে ক্রেডিট যোগ করতে পারে না।
• ৪২২: অবৈধ ঠিকানা বা তালিকার সীমা। ইনপুট সংশোধন করুন।
• ৫০৩ live_verification_unavailable: কার্যক্রম সাময়িক বন্ধ থাকার সময় নতুন লাইভ জমা ক্রেডিট হোল্ড না করেই এটি ফেরত দিতে পারে। পরে একই idempotency কী দিয়ে আবার চেষ্টা করুন। অনিশ্চিত জমার পরে ৫০৩ পেলে তা প্রমাণ করে না যে কোনো জব তৈরি হয়নি, তাই মূল কী-টিই আবার ব্যবহার করুন।

প্রতিটি ত্রুটিতে একটি কোড, একটি বার্তা ও একটি রিকোয়েস্ট আইডি থাকে। সাপোর্টে যোগাযোগের প্রয়োজনে হাতে রাখতে তিনটিই লগ করুন।

কাজের একটি যুক্তিসঙ্গত ক্রম

1. স্যান্ডবক্সে ইন্টিগ্রেশন তৈরি করুন এবং নিশ্চিত হোন যে প্রতিটি অনুকৃত ফলাফল প্রত্যাশিত জায়গায় পৌঁছায়।
2. উপরের ত্রুটি কোডগুলোর জন্য সুস্পষ্ট ব্যবস্থা যোগ করুন।
3. সবচেয়ে সীমিত প্রয়োজনীয় স্কোপ এবং আপনার বাজেটের সাথে মানানসই ক্যাপসহ একটি Live কী তৈরি করুন।
4. একটি ছোট লাইভ জব দিয়ে শুরু করুন। এর ফলাফল ও ক্রেডিটের অবস্থা ড্যাশবোর্ডের সাথে মিলিয়ে দেখুন, তারপর পরিসর বাড়ান।

এই ওয়ার্কফ্লো চেষ্টা করতে চাইলে, বিনামূল্যের স্যান্ডবক্সে কোনো ক্রেডিট ব্যবহার না করেই অনুকৃত ফলাফলগুলো পরীক্ষা করতে পারবেন। সঠিক রিকোয়েস্টের বিস্তারিত পাবেন API রেফারেন্সে।