दस्तावेज़ पर जाएँ
SDK

कॉन्फ़िगरेशन

क्लाइंट बनाने के तीन तरीके, हर option, और रिक्वेस्ट भेजे जाने से पहले वह क्या अस्वीकार करता है।

विकल्प

openemail.ts
import OpenEmail, { createOpenEmail, init, openemail } from '@openemail/sdk' init({ apiKey: process.env.OPENEMAIL_API_KEY })await openemail.me.ping() export const billing = createOpenEmail({ apiKey: process.env.BILLING_API_KEY! }) const pinned = new OpenEmail({ apiKey: 'oe_live_…', baseUrl: 'https://api.openemail.uk' }) const quick = new OpenEmail('oe_live_…')
प्रवेश बिंदुयह आपको क्या देता है
`init(options)`साझा क्लाइंट को कॉन्फ़िगर करके उसे लौटाता है। इसके बाद हर मॉड्यूल में openemail वही क्लाइंट होता है, और जो कुछ आप छोड़ देते हैं वह एनवायरनमेंट से पढ़ा जाता है।
`openemail`साझा क्लाइंट। init से पहले इस्तेमाल करने पर यह पहली कॉल पर खुद को OPENEMAIL_API_KEY और OPENEMAIL_BASE_URL से बना लेता है।
`createOpenEmail(options)`वही एनवायरनमेंट फ़ॉलबैक रखने वाला एक अलग क्लाइंट — साझा कुंजी के साथ-साथ दूसरी कुंजी के लिए, या वह instance बनाने के लिए जिसे आपका अपना मॉड्यूल export करता है। createClient वही फ़ंक्शन है, बस उस नाम से जो envless SDK इस्तेमाल करता है।
`new OpenEmail(options)` या `new OpenEmail(apiKey)`एक अलग क्लाइंट, जो ठीक उसी से बनता है जो आप पास करते हैं। यह एनवायरनमेंट नहीं पढ़ता, इसलिए apiKey ज़रूरी है। यही default export भी है।
options.ts
init({  apiKey: 'oe_live_…',  baseUrl: 'https://api.openemail.uk',  timeoutMs: 30_000,  maxRetries: 2,  fetch: myFetch,  headers: {},  userAgent: 'billing-service/1.4',  disableUpdateNotice: true,})
विकल्पडिफ़ॉल्टटिप्पणियाँ
`apiKey`OPENEMAIL_API_KEYinit और createOpenEmail इसे एनवायरनमेंट से पढ़ते हैं। इसकी शुरुआत oe_live_ या oe_test_ से होनी चाहिए।
`baseUrl`https://api.openemail.ukया OPENEMAIL_BASE_URL। आख़िर का slash हटा दिया जाता है, और init तथा createOpenEmail सादे होस्ट के आगे https:// लगाते हैं, और localhost के आगे http://।
`timeoutMs`30000प्रति प्रयास, प्रति कॉल नहीं। यह सिर्फ़ headers ही नहीं, body पढ़ने को भी कवर करता है। 0 इसे बंद कर देता है।
`maxRetries`2पहली कोशिश के बाद के अतिरिक्त प्रयास, उन कॉलों पर जिन्हें दोहराना सुरक्षित है। यह क्लाइंट पर सेट होता है, प्रति कॉल नहीं।
`fetch`ग्लोबल वालाआपके लिए bind कर दिया गया। proxy, Worker binding या test double के लिए अपना ख़ुद का पास करें।
`headers`{}हर रिक्वेस्ट पर भेजा जाता है।
`userAgent`openemail-sdk/<version>ब्राउज़र को छोड़कर हर runtime से भेजा जाता है; ब्राउज़र इसे सेट करने नहीं देता।
`disableUpdateNotice`falsenpm पर नए वर्शन की प्रति-प्रोसेस-एक-बार वाली जाँच को छोड़ देता है। यह जाँच तभी चलती है जब आउटपुट किसी terminal पर जा रहा हो, और OPENEMAIL_DISABLE_UPDATE_NOTICE भी इसे बंद कर देता है।
`dangerouslyAllowBrowser`falseक्लाइंट को वहाँ शुरू होने देता है जहाँ window और document मौजूद हों। यह उन्हें परिभाषित करने वाले test harness के लिए है, किसी पेज के लिए नहीं।

भेजने से पहले यह क्या अस्वीकार करता है

ये आपके पहले send पर किसी उलझाऊ विफलता के रूप में सामने आने के बजाय उसी पंक्ति से एक सादा Error फेंकते हैं जिसमें ग़लत मान था। संदेश बताता है कि क्या ग़लत था और उसकी जगह क्या पास करना है।

अस्वीकृतक्यों
कोई कुंजी ही नहींन apiKey सेट था और न OPENEMAIL_API_KEY, इसलिए प्रमाणीकरण के लिए कुछ है ही नहीं।
कोई session cookie या session tokenयहाँ केवल oe_live_ और oe_test_ ही प्रमाणित होते हैं, और API भी यही कहता है। यह जाँच सिर्फ़ prefix देखती है, इससे ज़्यादा कुछ नहीं, इसलिए रद्द की गई कुंजी फिर भी नेटवर्क पर जाकर ही विफल होती है।
ऐसा `baseUrl` जो http या https URL न होऔर कुछ fetch किया ही नहीं जा सकता, और बिना जाँचा हुआ मान बाद में कहीं और से आए किसी कच्चे TypeError के रूप में विफल होता।
कोई ब्राउज़रdevtools खोलने वाला कोई भी व्यक्ति कुंजी पढ़ सकेगा। नीचे का खंड देखें।
कहीं भी `fetch` नहींfetch के रूप में एक पास करें, या Node 20+ पर चलाएँ।
किसी भी method पर खाली या सिर्फ़ बिंदुओं वाला idmethod कॉल होते ही फेंका जाता है। बिंदुओं वाला path segment हर URL parser हटा देता है, इसलिए रिक्वेस्ट किसी दूसरे endpoint पर पहुँच जाती।

testMode नाम का कोई विकल्प नहीं है और न होगा। कुंजी की योजना संकेत नहीं, बल्कि credential का हिस्सा है, इसलिए mode कुंजी का ही गुण है। openemail.mode prefix पढ़ता है और तय कुछ नहीं करता।

एक क्लाइंट, कई कुंजियाँ

क्लाइंट एक बार बनाइए और उसी को साझा कीजिए। हर रिक्वेस्ट पर नया instance बनाना fetch binding और कॉन्फ़िगरेशन को बेवजह फेंक देता है, और उस पर रखी कोई भी स्थिति प्रति-कॉलर नहीं होती।

जिस स्थिति में वरना हर कुंजी के लिए एक instance बनाना पड़ता — जैसे कई workspaces की ओर से भेजने वाला कोई job — वहाँ कॉल पर ही apiKey पास करें। यह उस रिक्वेस्ट के लिए Authorization header बदल देता है और क्लाइंट पर कुछ भी पीछे नहीं छोड़ता।

per-call-key.ts
await openemail.emails.send(message) await openemail.emails.send(message, { apiKey: workspace.apiKey }) await openemail.threads.list({ folder: 'inbox', apiKey: workspace.apiKey })await openemail.webhooks.list({ apiKey: workspace.apiKey })

tempMail के बाहर हर method इसे अपने अंतिम आर्ग्युमेंट में signal के साथ लेता है, और किसी list पर वह वही ऑब्जेक्ट होता है जिसमें फ़िल्टर हैं। रिक्वेस्ट भेजे जाने से पहले इसकी जाँच उसी नियम से होती है जो constructor इस्तेमाल करता है, इसलिए टाइपो पर { apiKey } on this call का नाम लेता हुआ एक Error मिलता है, न कि किसी ऐसे credential के बारे में 401 जिसे फिर आपको ढूँढ़ने जाना पड़े। दोबारा की गई कॉल वही कुंजी रखती है जो उसे दी गई थी।

signal एक AbortSignal है। इसे abort करने पर रिक्वेस्ट रुक जाती है, और उसके पीछे प्रतीक्षा कर रहा कोई भी retry भी।

openemail.mode उस कुंजी का वर्णन करता है जिससे क्लाइंट बनाया गया था और यह किसी override के पीछे नहीं चलता। जब एक ही क्लाइंट कई कुंजियों को सेवा देता है तो बताने लायक कोई एक mode रहता ही नहीं, इसलिए इसे उसी कुंजी से पढ़ें जो आपने पास की थी।

ब्राउज़र से

क्लाइंट ब्राउज़र में शुरू होने से इनकार करता है और कोई भी रिक्वेस्ट जाने से पहले ही throw कर देता है। पेज में रखी कुंजी प्रकाशित कुंजी है: devtools खोलने वाले किसी भी व्यक्ति के लिए वह मेल भेज सकती है और मेलबॉक्स पढ़ सकती है। इसे किसी सर्वर, serverless फ़ंक्शन या स्क्रिप्ट से कॉल करें।

डिस्पोज़ेबल इनबॉक्स अपवाद हैं। createTempMail() ऐसा क्लाइंट बनाता है जो कोई API कुंजी नहीं रखता, इसलिए वह पेज में सुरक्षित है। यह गुमनाम रूप से इनबॉक्स बनाता है, और हर पढ़ाई उस टोकन को भेजती है जो create ने लौटाया था — या तो प्रति कॉल inboxToken के रूप में, या एक बार createTempMail({ inboxToken }) के रूप में।

temp-mail.ts
import { createTempMail } from '@openemail/sdk' const tempMail = createTempMail() const inbox = await tempMail.create()const { items, expiresAt } = await tempMail.listMessages(inbox.id, { inboxToken: inbox.token })

जहाँ आप फिर भी dangerouslyAllowBrowser: true पास करते हैं, वहाँ API अपने CORS preflight से ठीक Content-Type, Authorization और Idempotency-Key ही गुज़रने देता है, इसलिए headers में कोई अतिरिक्त header रिक्वेस्ट को नहीं, preflight को विफल करता है — और उसके बारे में ब्राउज़र जो बताता है उसमें कोई काम की बात नहीं होती।