नॉलेज बेस
REST API
एक प्रलेखित HTTP API, जिसकी कुंजियाँ जारी, स्कोप और रद्द की जा सकती हैं।
विवरण
- हर जगह चालू। API 68 पाथ पर 104 प्रलेखित ऑपरेशन देता है (emails, threads, drafts, labels, contacts, audiences, domains, templates, rules, roles, members, settings, calendar, tracking, webhooks और खाता) एक प्रतिबद्ध OpenAPI 3.1 दस्तावेज़ के पीछे, जिसे आप बिना कुंजी के GET /openapi.json पर पढ़ सकते हैं। एक्सेस उस वर्कस्पेस कुंजी से तय होता है जो आप Settings में जारी करते हैं।
- जिस टिकाऊपन का यह पहले इंतज़ार कर रहा था वह पूरा हो चुका है। कुछ भी भेजे जाने से पहले एक सेंड एक पंक्ति लिखता है, जिसकी सार्वजनिक id msg_ के बाद 24 hex के रूप में होती है, और GET /emails/{id} उसे हल करता है, साथ ही प्रति-प्राप्तकर्ता निशान के लिए /events और opens तथा clicks के लिए /tracking। 1–255 वर्णों की एक Idempotency-Key, कुंजी और आपकी API कुंजी दोनों पर बने एक यूनिक इंडेक्स के विरुद्ध दावा की जाती है, इसलिए टाइमआउट के बाद दोबारा प्रयास दो बार भेजने के बजाय Idempotency-Replayed: true के साथ पहला परिणाम लौटाता है। कुंजी से किया गया सेंड निपट जाने पर 200 और कतार में या शेड्यूल्ड रहते हुए 202 लौटाता है।
- कुंजियाँ Settings → API keys में बनाई, स्कोप की, घुमाई और रद्द की जाती हैं। कंसोल जो भी कुंजी जारी करता है वह oe_live_ वाली होती है। oe_test_ उपसर्ग को सत्यापक और सेंड पाथ दोनों समझते हैं, जहाँ टेस्ट-मोड सेंड किसी ट्रांसपोर्ट तक पहुँचे बिना दर्ज होता है और sent के रूप में उत्तर देता है, लेकिन अभी कुछ भी ऐसी कुंजी नहीं बना सकता, और Durable Object के ऊपर no-op ट्रांसपोर्ट आने से पहले यह विकल्प देना आपको ऐसी टेस्ट कुंजी थमा देता जो सचमुच मेल पहुँचा देती। एक कुंजी अधिकतम 25 पूरे डोमेन और 50 एकल पतों का सेंड स्कोप रखती है, जहाँ पूरा डोमेन बाद में उसमें जोड़े गए पतों को भी कवर करता है, 1 से 3650 दिनों के बीच एक वैकल्पिक समाप्ति, और वैकल्पिक रूप से एक भूमिका। भूमिका दूसरी अनुमति नहीं, बल्कि एक छत है: GET /ping कुंजी पर मौजूद स्कोप और भूमिका द्वारा छोड़े गए स्कोप, दोनों लौटाता है, ताकि जिस स्कोप का नाम आपकी कुंजी साफ़-साफ़ लेती है उस पर मिले 403 का कारण दिखाई दे। रद्द करना डिलीट नहीं, अपडेट है, इसलिए बाद की कॉल को केवल प्रमाणीकरण विफल होने के बजाय revoked_api_key बताया जाता है। घुमाने पर गुप्त हिस्से के सिवा कुंजी का सब कुछ बना रहता है: id, स्कोप, सेंड स्कोप और अनुरोध इतिहास चलते रहते हैं, नई कुंजी बनते ही पुरानी गुप्त कुंजी मर जाती है, और keys:write रखने वाली कुंजी API पर खुद को घुमा सकती है। सूची बनाने, घुमाने, रद्द करने और सक्षम करने की यही क्रियाएँ MCP सर्वर पर भी उपलब्ध हैं, हर उस व्यक्ति के लिए जिसकी भूमिका कुंजियाँ प्रबंधित कर सकती है।
- जो सचमुच नहीं है: API के पास अपना कोई अपलोड एंडपॉइंट नहीं है। इनलाइन अटैचमेंट कुल 5 MB की सीमा के भीतर base64 के रूप में जाते हैं, और बड़ी फ़ाइल वर्कस्पेस में पहले से मौजूद किसी फ़ाइल का उसकी id से नाम लेकर भेजी जाती है, जो एक डाउनलोड लिंक के रूप में जाती है। बाउंस सेंड लॉग के बजाय मेलबॉक्स में संभाले जाते हैं: डिलीवरी रिपोर्ट पार्स की जाती है, Message-ID से मूल संदेश से मिलाई जाती है, थ्रेड पर लेबल की जाती है और email.bounced वेबहुक के रूप में भेजी जाती है, लेकिन कुछ भी सेंड पंक्ति में वापस नहीं लिखता, जिसकी status में कोई bounced अवस्था है ही नहीं, इसलिए GET /emails के ज़रिए बाउंस हुआ संदेश अब भी sent ही पढ़ा जाता है। ऐप के कंपोज़र से भेजी गई मेल भी GET /emails में नहीं दिखती, क्योंकि कंपोज़र उसी सेंड पाथ से होकर नहीं लिखता।