AI एजेंट्स के लिए ईमेल भेजना सेट करें
कोडिंग एजेंट्स और असिस्टेंट्स के लिए एक मशीन-रीडेबल मार्ग, जिन्हें किसी और के प्रोजेक्ट में ट्रांज़ैक्शनल ईमेल जोड़ना है — क्या कॉल करना है, किस क्रम में, और हर भेजने से पहले कौन-सी जाँचें चलानी हैं।
OpenAPI 3.1 डाउनलोड करेंकोई भी कोड लिखने से पहले
- उपयोगकर्ता से एक प्रोजेक्ट API key माँगें, या उन्हें https://app.srs-postline.com/hi/login पर एक sandbox key बनाने के लिए कहें — किसी अन्य प्रोजेक्ट की key कभी न गढ़ें, अनुमान न लगाएं, या पुनः उपयोग न करें।
- key को एक सर्वर-साइड environment variable में रखें। इसे frontend कोड, मोबाइल ऐप बंडल, सार्वजनिक repo, या कमिट किए गए .env फ़ाइल में न रखें।
- रिक्वेस्ट कोड बनाने से पहले /llms.txt और openapi/postline.yaml पढ़ें; फ़ील्ड के नाम या एंडपॉइंट का अनुमान न लगाएं।
न्यूनतम भेजना
POST /v1/emails
Authorization: Bearer srs_live_...
Idempotency-Key: <stable-id-per-logical-send>
Content-Type: application/json
{
"from": "Sender Name <info@example.com>",
"to": ["user@example.net"],
"subject": "विषय",
"html": "<p>संदेश</p>",
"text": "संदेश"
}हर भेजने से पहले चलाने वाली जाँचें
- हमेशा ट्रिगर करने वाली क्रिया (order ID, event ID) से प्राप्त एक Idempotency-Key भेजें ताकि पुनः प्रयास से डबल-सेंड न हो।
- OTP कोड, पासवर्ड-रीसेट टोकन, या अन्य गुप्त जानकारी को कभी भी किसी ऐसे फ़ील्ड में न डालें जो लॉग हो या संदेश के मुख्य भाग के बाहर फॉरवर्ड हो।
- कार्य के लिए आवश्यक सबसे संकीर्ण API key scope माँगें (भेजने के लिए emails:send पर्याप्त है; जब तक कार्य को इसकी आवश्यकता न हो, domains:write या api_keys:write न माँगें)।
- हर कॉल में अधिकतम 100 प्राप्तकर्ता रखें। मौजूदा API attachment या custom header स्वीकार नहीं करता; फ़ाइल अस्वीकार करें या लिंक दें, उसे संलग्न बताकर प्रस्तुत न करें।
- 4xx प्रतिक्रियाओं पर चुपचाप पुनः प्रयास न करें। केवल 429 और 503 को ही पुनः प्रयास करना सुरक्षित है, और वह भी केवल backoff के साथ।
हर प्रतिक्रिया कोड को संभालें
- 202 — कतार में डाला गया, डिलीवर नहीं हुआ। यदि बाद में स्थिति जाँचनी हो तो लौटाई गई id को सेव करें।
- 400 — अमान्य payload; अनुरोध को ठीक करें, बिना बदलाव के पुनः प्रयास न करें।
- 401 — अमान्य या समाप्त हो चुकी key; रुकें और यह उपयोगकर्ता को दिखाएं, नई key न गढ़ें।
- 403 — scope अनुपस्थित है या भेजने वाला डोमेन अभी सत्यापित नहीं हुआ है; उपयोगकर्ता को आगे बढ़ने से पहले डोमेन सत्यापित करने के लिए कहें।
- 422 — प्राप्तकर्ता suppressed है (पिछला bounce/complaint); उस प्राप्तकर्ता के लिए पुनः प्रयास न करें।
- 429 — rate limited; रुकें और बाद में पुनः प्रयास करें, tight loop में न फंसें।
- 503 — कतार अनुपलब्ध; backoff के साथ पुनः प्रयास करें, किसी अनौपचारिक ट्रांसपोर्ट पर न जाएं।
यदि कार्य में इवेंट प्राप्त करना शामिल है
केवल HTTPS पर एक webhook एंडपॉइंट रजिस्टर करें। किसी भी payload पर भरोसा करने से पहले हस्ताक्षर की स्वयं पुनर्गणना करें; यह सोचकर सत्यापन न छोड़ें कि अनुरोध 'आंतरिक जैसा लगता है'।
signature = HMAC-SHA256(webhook_secret, timestamp + "\0" + event_id + "\0" + raw_body)
header Postline-Signature से तुलना करें (constant-time compare)
यदि Postline-Timestamp आपकी अनुमत विंडो से बाहर है तो अस्वीकार करें
event_id सेव करें और हर इवेंट को ठीक एक बार प्रोसेस करेंमशीन-रीडेबल संदर्भ
- /llms.txt — एजेंट कॉन्टेक्स्ट विंडो के लिए इन नियमों का संक्षिप्त इंडेक्स।
- /openapi/postline.yaml — हर एंडपॉइंट के लिए पूर्ण OpenAPI 3.1 स्कीमा।
- /hi/api/ — मानव-पठनीय API reference।
- /hi/webhooks/ — webhook हस्ताक्षर और पुनः प्रयास विवरण।
वर्तमान access model
वर्तमान keys srs_live_ उपयोग करती हैं। From domain verify होने से पहले shared sandbox sender केवल project members को भेज सकता है। उसके बाद plan quota, suppression, recipient throttling और abuse controls लागू रहते हैं। 202 का अर्थ queued है, delivered नहीं।
इंटीग्रेशन संसाधन
मनुष्यों और AI agents के लिए step-by-step guide उपयोग करें; fields के लिए OpenAPI source of truth है।