বাল্ক ইমেইল যাচাই API: ব্যাচ জবের একটি ব্যবহারিক ওয়ার্কফ্লো

বাল্ক ইমেইল যাচাই API: ব্যাচ জবের একটি ব্যবহারিক ওয়ার্কফ্লো

প্রশ্ন: আপনার নিজস্ব সিস্টেমে ঠিকানার একটি বড় তালিকা আছে। ক্রেডিটের হিসাব না হারিয়ে কীভাবে সেটি ব্যাচে ব্যাচে FairValid API-এর মাধ্যমে পাঠাবেন, নিরাপদে ত্রুটি সামলাবেন এবং ফলাফল ফেরত পড়বেন?

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

১৩ নভেম্বর, ২০২৬ তারিখে FairValid-এর API রেফারেন্স, ফলাফল নির্দেশিকা এবং ক্রেডিট নিয়মাবলি-এর সঙ্গে মিলিয়ে তথ্যপ্রমাণ যাচাই করা হয়েছে।

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

API রেফারেন্স অনুযায়ী, API কী অংশে একটি Test কী তৈরি করুন, সেটি আপনার সার্ভারে রাখুন এবং বেস URL-সহ আপনার এনভায়রনমেন্টে সেট করুন। Test কী example.com ডোমেইনের সংরক্ষিত ঠিকানাগুলোর সঙ্গে কাজ করে। এগুলো কোনো প্রোভাইডার কল করে না এবং কোনো ক্রেডিট ব্যবহার করে না। Test কী কেবল নিজস্ব সিমুলেটেড জবে অ্যাক্সেস পায়।

Test জবগুলো নির্ধারিত অবস্থা ফেরত দেয়: completed, pending, failed অথবা cancelled। সুনির্দিষ্ট স্যান্ডবক্স ঠিকানার জন্য API রেফারেন্স দেখুন, এবং আপনার কোড এই অবস্থাগুলো সামলাতে পারে কি না তা নিশ্চিত করতে সেগুলো ব্যবহার করুন। এই কেসগুলো কেবল সেই ফলাফলগুলোই দেখায়, যেগুলোর জন্য এগুলো তৈরি করা হয়েছে। এগুলো আপনার ইন্টিগ্রেশনের প্রতিটি শাখা কভার করে না, তাই নিজের ত্রুটি-পথগুলো আলাদাভাবে পর্যালোচনা করুন।

ধাপ ২: সঠিক স্কোপসহ Live কী-তে যান

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

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

ধাপ ৩: তালিকা ভাগ করুন ও জব জমা দিন

প্রতিটি জব JSON-এ ১ থেকে ৫,০০০টি ঠিকানা গ্রহণ করে, সর্বোচ্চ ২ MiB পর্যন্ত। এখানে একটি ব্যবহারিক পদ্ধতি দেওয়া হলো:

1. তালিকাটি খণ্ডে ভাগ করুন। উদাহরণস্বরূপ, ১২,০০০টি ঠিকানা ৫,০০০, ৫,০০০ ও ২,০০০টির তিনটি জবে পরিণত হবে।
2. প্রতিটি খণ্ডকে নিজস্ব স্থির Idempotency-Key দিন, এবং আপনার কোন সারি কোন খণ্ডে গেছে তা লিখে রাখুন। এই ম্যাপিং নিজের দিকে রাখলে ফলাফলগুলো আপনার রেকর্ডের সঙ্গে মেলানো সহজ হয়।
3. jobs এন্ডপয়েন্টে জমা দিন। নতুন জব একটি UUID job_id-সহ HTTP ২০২ ফেরত দেয়। মিলে যাওয়া পুনঃচেষ্টা একই জবসহ HTTP ২০০ ফেরত দেয়। অর্থাৎ টাইমআউটের পর একই কী দিয়ে একই অনুরোধ আবার পাঠিয়ে বিদ্যমান জবটি ফেরত পেতে পারেন।

ধাপ ৪: দেখতে একরকম দুটি ত্রুটি সামলান

এই দুটি রেসপন্সই জমা দেওয়া আটকে দিতে পারে, কিন্তু এদের অর্থ ভিন্ন:

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

এই দুটি রেসপন্স অনুমতি-সংক্রান্ত ত্রুটি ও প্রসেসিং সীমা থেকে আলাদাভাবে লগ করুন, যাতে সঠিক ব্যক্তি সঠিক সতর্কবার্তা পান।

ধাপ ৫: জবের অবস্থা ট্র্যাক করুন, তারপর ফলাফল পেজ করুন

job এন্ডপয়েন্ট একটি জবের বর্তমান অবস্থা ও সারসংক্ষেপ ফেরত দেয়। জবের স্ট্যাটাস হতে পারে queued, running, paused, canceling, canceled অথবা completed। আপনি বাতিলের অনুরোধ করলেও যে কাজ ইতিমধ্যে চলমান, তা তবুও শেষ হতে পারে।

results এন্ডপয়েন্ট একবারে সর্বোচ্চ ৫০টি ফলাফল ফেরত দেয়, সঙ্গে একটি স্বাক্ষরিত next_cursor। সেই মানটি cursor কোয়েরি প্যারামিটার হিসেবে পাঠান। এটি আপনার মূল ফিল্টার ও সার্চ বহাল রাখে। ফিল্টারগুলো হলো all, valid, invalid, catch_all, unknown, still_checking এবং not_checked। এগুলো দিয়ে কেবল সেই সারিগুলো আনতে পারেন যেগুলোর জন্য সিদ্ধান্ত দরকার, যেমন unknown চিহ্নিত সবকিছু।

ধাপ ৬: ফলাফলকে সিদ্ধান্তে রূপ দিন

ফলাফল নির্দেশিকা ফলাফলকে তথ্যপ্রমাণ হিসেবে বর্ণনা করে, ডেলিভারির নিশ্চয়তা হিসেবে নয়:

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

কারিগরি ব্যর্থতা ও অপ্রক্রিয়াজাত আইটেম একটি আলাদা শ্রেণি। FairValid-এর ক্রেডিট নিয়মাবলি অনুযায়ী, এগুলোকে অজানা হিসেবে পুনঃলেবেল করা হয় না।

ধাপ ৭: ক্রেডিট সংরক্ষণ বুঝে নিন

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

balance এন্ডপয়েন্ট লাইভ ওয়ার্কস্পেসের উপলব্ধ ও আটকে রাখা ক্রেডিটের হিসাব দেয়। এর free_allowance_held ফিল্ড true হলে বিনামূল্যের বরাদ্দ স্থগিত থাকে এবং available_credits বা free_available-এ গণনা হয় না। পেইড ক্রেডিট উপলব্ধ থাকে। মূল অ্যাকাউন্টটি প্রতি মাসে সাইনআপের তারিখে ৩০০টি বিনামূল্যের ক্রেডিট পায়, এবং অব্যবহৃত বিনামূল্যের ক্রেডিট পরের মাসে যায় না। অতিরিক্ত ওয়ার্কস্পেস আলাদা কোনো বিনামূল্যের বরাদ্দ পায় না। বিনামূল্যের ক্রেডিট আগে ব্যবহৃত হয়, এবং অ্যাকাউন্ট চালু থাকা পর্যন্ত পেইড ক্রেডিটের মেয়াদ শেষ হয় না।

একটি সহজ চেকলিস্ট

• Test কী এবং নথিভুক্ত স্যান্ডবক্স কেস দিয়ে পরীক্ষা করুন।
• submit ও read স্কোপসহ একটি Live কী ব্যবহার করুন, যার সীমা পরিকল্পিত কাজের সঙ্গে মানানসই।
• প্রতিটি খণ্ড ৫,০০০টি বা তার কম ঠিকানায় রাখুন, এবং প্রতিটি খণ্ডের জন্য একটি করে স্থির idempotency কী দিন।
• ৫০৩ পেলে পরে একই কী দিয়ে আবার চেষ্টা করুন। ৪০২ পেলে অপেক্ষা করবেন না; বরং সীমার বিষয়টি সমাধান করুন।
• ফলাফল অনুযায়ী ফিল্টার করে স্বাক্ষরিত কার্সর দিয়ে ফলাফল পেজ করুন।
• আপনার ডেটায় অপেক্ষমাণ, কারিগরি ব্যর্থতা ও অজানা আলাদা রাখুন।

এই ওয়ার্কফ্লো চেষ্টা করতে চাইলে, প্রথম লাইভ জমা দেওয়ার আগে একটি Test কী তৈরি করে ক্রেডিট খরচ না করেই একটি স্যান্ডবক্স জব চালাতে পারেন। এন্ডপয়েন্টের পূর্ণ বিবরণ API রেফারেন্সে পাওয়া যাবে।