AI এজেন্টদের জন্য ইমেইল পাঠানো সেট আপ করুন
কোডিং এজেন্ট এবং অ্যাসিস্ট্যান্টদের জন্য একটি মেশিন-রিডেবল পথ, যাদের অন্য কারো প্রজেক্টে ট্রানজ্যাকশনাল ইমেইল যোগ করতে হয় — কী কল করতে হবে, কোন ক্রমে, এবং প্রতিটি পাঠানোর আগে কোন চেকগুলো চালাতে হবে।
OpenAPI 3.1 ডাউনলোড করুনকোনো কোড লেখার আগে
- ব্যবহারকারীর কাছে একটি প্রজেক্ট API কী চান, অথবা তাদের https://app.srs-postline.com/bn/login -এ একটি sandbox কী তৈরি করতে বলুন — কখনো কী উদ্ভাবন, অনুমান বা অন্য প্রজেক্ট থেকে পুনঃব্যবহার করবেন না।
- কীটি একটি সার্ভার-সাইড এনভায়রনমেন্ট ভেরিয়েবলে রাখুন। এটি frontend কোড, মোবাইল অ্যাপ বান্ডল, পাবলিক রিপো, বা কমিট করা .env ফাইলে রাখবেন না।
- রিকোয়েস্ট কোড তৈরি করার আগে /llms.txt এবং openapi/postline.yaml পড়ুন; ফিল্ডের নাম বা endpoint অনুমান করবেন না।
সর্বনিম্ন পাঠানো
POST /v1/emails
Authorization: Bearer srs_live_...
Idempotency-Key: <প্রতি-পাঠানোর-স্থিতিশীল-id>
Content-Type: application/json
{
"from": "Sender Name <info@example.com>",
"to": ["user@example.net"],
"subject": "বিষয়",
"html": "<p>বার্তা</p>",
"text": "বার্তা"
}প্রতিটি পাঠানোর আগে চালানোর চেক
- সবসময় ট্রিগারকারী অ্যাকশন (অর্ডার ID, ইভেন্ট ID) থেকে প্রাপ্ত একটি Idempotency-Key পাঠান যাতে retry-তে দ্বিগুণ পাঠানো না হয়।
- OTP কোড, পাসওয়ার্ড-রিসেট টোকেন, বা অন্য কোনো সিক্রেট এমন কোনো ফিল্ডে রাখবেন না যা লগ করা হয় বা বার্তার বডির বাইরে ফরওয়ার্ড করা হয়।
- কাজের জন্য প্রয়োজনীয় সবচেয়ে সংকীর্ণ API কী scope অনুরোধ করুন (পাঠানোর জন্য emails:send যথেষ্ট; কাজের প্রয়োজন না হলে domains:write বা api_keys:write চাইবেন না)।
- প্রতি কলে সর্বোচ্চ 100 জন প্রাপক রাখুন। বর্তমান API attachment বা custom header গ্রহণ করে না; ফাইল প্রত্যাখ্যান করুন বা লিংক দিন, সংযুক্ত হয়েছে বলে দাবি করবেন না।
- 4xx রেসপন্সে নীরবে retry করবেন না। শুধুমাত্র 429 এবং 503 retry করা নিরাপদ, এবং শুধুমাত্র backoff সহ।
প্রতিটি রেসপন্স কোড হ্যান্ডেল করুন
- 202 — queue করা হয়েছে, ডেলিভার হয়নি। পরে স্ট্যাটাস দেখার প্রয়োজন হলে রিটার্ন হওয়া id সংরক্ষণ করুন।
- 400 — অবৈধ payload; অনুরোধ ঠিক করুন, অপরিবর্তিতভাবে retry করবেন না।
- 401 — অবৈধ বা মেয়াদোত্তীর্ণ কী; থামুন এবং এটি ব্যবহারকারীকে জানান, নতুন কী বানাবেন না।
- 403 — scope অনুপস্থিত অথবা sending ডোমেইন এখনো যাচাই করা হয়নি; এগিয়ে যাওয়ার আগে ব্যবহারকারীকে ডোমেইন যাচাই করতে বলুন।
- 422 — প্রাপক suppressed (অতীত bounce/complaint); সেই প্রাপকের জন্য retry করবেন না।
- 429 — rate limited; পিছিয়ে যান এবং পরে retry করুন, শক্তভাবে লুপ করবেন না।
- 503 — queue অনুপলব্ধ; backoff সহ retry করুন, কোনো অনানুষ্ঠানিক ট্রান্সপোর্টে ফিরে যাবেন না।
যদি কাজে ইভেন্ট গ্রহণ করা অন্তর্ভুক্ত থাকে
শুধুমাত্র HTTPS-এর মাধ্যমে একটি webhook endpoint নিবন্ধন করুন। কোনো payload বিশ্বাস করার আগে নিজে স্বাক্ষর পুনঃগণনা করুন; কোনো অনুরোধ 'অভ্যন্তরীণ মনে হচ্ছে' বলে যাচাই এড়িয়ে যাবেন না।
signature = HMAC-SHA256(webhook_secret, timestamp + "\0" + event_id + "\0" + raw_body)
Postline-Signature হেডারের সাথে তুলনা করুন (constant-time compare)
Postline-Timestamp অনুমোদিত উইন্ডোর বাইরে থাকলে প্রত্যাখ্যান করুন
event_id সংরক্ষণ করুন এবং প্রতিটি ইভেন্ট ঠিক একবার প্রক্রিয়া করুনমেশিন-রিডেবল রেফারেন্স
- /llms.txt — এজেন্ট context window-এর জন্য এই নিয়মগুলোর সংক্ষিপ্ত সূচি।
- /openapi/postline.yaml — প্রতিটি endpoint-এর সম্পূর্ণ OpenAPI 3.1 স্কিমা।
- /bn/api/ — মানুষের জন্য API রেফারেন্স।
- /bn/webhooks/ — webhook স্বাক্ষর এবং retry বিস্তারিত।
বর্তমান access model
বর্তমান key srs_live_ ব্যবহার করে। From domain যাচাইয়ের আগে shared sandbox sender শুধু project member-কে পাঠাতে পারে। এরপর plan quota, suppression, recipient throttling ও abuse control প্রযোজ্য। 202 মানে queued, delivered নয়।
ইন্টিগ্রেশন রিসোর্স
মানুষ ও AI agent-এর step-by-step guide ব্যবহার করুন; field-এর source of truth হলো OpenAPI।