Konfiguráció
Háromféleképpen építhetsz klienst, az összes beállítási lehetőség, és amit a kérés elküldése előtt elutasít.
Beállítások
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_…')| Belépési pont | Mit ad |
|---|---|
| `init(options)` | Beállítja a közös klienst, és visszaadja. Az openemail attól kezdve minden modulban ez a kliens, és amit kihagysz, azt a környezetből olvassa. |
| `openemail` | A közös kliens. Ha init előtt használod, az első híváskor az OPENEMAIL_API_KEY és az OPENEMAIL_BASE_URL értékekből építi fel magát. |
| `createOpenEmail(options)` | Külön kliens ugyanazzal a környezeti tartalékkal, egy második kulcshoz a közös mellett, vagy ahhoz, hogy a saját modulod által exportált példányt építsd fel. A createClient ugyanez a függvény azon a néven, amelyet az envless SDK használ. |
| `new OpenEmail(options)` vagy `new OpenEmail(apiKey)` | Külön kliens, pontosan abból felépítve, amit átadsz. Nem olvas környezetet, így az apiKey kötelező. Egyben ez az alapértelmezett export is. |
init({ apiKey: 'oe_live_…', baseUrl: 'https://api.openemail.uk', timeoutMs: 30_000, maxRetries: 2, fetch: myFetch, headers: {}, userAgent: 'billing-service/1.4', disableUpdateNotice: true,})| Beállítás | Alapértelmezés | Megjegyzések |
|---|---|---|
| `apiKey` | OPENEMAIL_API_KEY | Az init és a createOpenEmail a környezetből olvassa. oe_live_ vagy oe_test_ előtaggal kell kezdődnie. |
| `baseUrl` | https://api.openemail.uk | Vagy OPENEMAIL_BASE_URL. A záró perjelet levágjuk, az init és a createOpenEmail pedig https:// előtagot tesz a csupasz hosztnév elé, localhost esetén http:// előtagot. |
| `timeoutMs` | 30000 | Próbálkozásonként, nem hívásonként. A törzs beolvasására is vonatkozik, nem csak a fejlécekre. A 0 kikapcsolja. |
| `maxRetries` | 2 | További próbálkozások az első után, azokon a hívásokon, amelyeket biztonságos megismételni. A kliensen állítható be, nem hívásonként. |
| `fetch` | a globális | Készen kötve kapod. Adj át sajátot proxyhoz, Worker-bindinghez vagy teszthelyettesítőhöz. |
| `headers` | {} | Minden kérésen elküldjük. |
| `userAgent` | openemail-sdk/<version> | Minden futtatókörnyezetből elküldjük a böngészőt kivéve, amely nem engedi beállítani. |
| `disableUpdateNotice` | false | Kihagyja a folyamatonként egyszeri ellenőrzést, amely újabb verziót keres az npm-en. Az ellenőrzés csak akkor fut, ha a kimenet terminálra megy, és az OPENEMAIL_DISABLE_UPDATE_NOTICE is kikapcsolja. |
| `dangerouslyAllowBrowser` | false | Engedi, hogy a kliens ott is elinduljon, ahol létezik window és document. Olyan tesztkörnyezethez való, amely ezeket definiálja, nem weboldalhoz. |
Mit utasít el küldés előtt
Ezek sima Error kivételt dobnak arról a sorról, amelyen a hibás érték volt, ahelyett hogy az első küldésednél zavaros hibaként bukkannának fel. Az üzenet megmondja, mi volt a baj, és mit adj át helyette.
| Elutasítva | Miért |
|---|---|
| Egyáltalán nincs kulcs | Sem az apiKey, sem az OPENEMAIL_API_KEY nem volt beállítva, így nincs mivel hitelesíteni. |
| Munkamenet-süti vagy munkamenet-token | Itt csak az oe_live_ és az oe_test_ hitelesít, és az API is ezt mondja. Az ellenőrzés csupán előtagvizsgálat, tehát egy visszavont kulcs továbbra is a hálózaton bukik meg. |
| Olyan `baseUrl`, amely nem http vagy https URL | Mást nem lehet lekérni, és egy ellenőrizetlen érték később nyers TypeError formájában bukna el valahol egészen máshol. |
| Böngésző | A kulcsot bárki elolvashatná, aki megnyitja a fejlesztői eszközöket. Lásd az alábbi szakaszt. |
| Sehol nincs `fetch` | Adj át egyet a fetch beállításban, vagy futtasd Node 20+ alatt. |
| Üres vagy csupa pontból álló azonosító bármelyik metóduson | A metódus hívásakor dobódik. A csupa pontból álló útvonalszegmenst minden URL-elemző eltávolítja, így a kérés más végpontra érkezne. |
Nincs testMode beállítás, és nem is lesz. A kulcsséma a hitelesítő adat része, nem utalás, így a mód a kulcs tulajdonsága. Az openemail.mode az előtagot olvassa, és semmiről nem dönt.
Egy kliens, több kulcs
Építsd fel a klienst egyszer, és használd közösen. A kérésenként létrehozott új példány feleslegesen dobja el a fetch-kötést és a konfigurációt, és az állapotából semmi nem hívófüggő.
Arra az esetre, amely egyébként kulcsonként külön példányt kényszerítene ki – például egy több munkaterület nevében küldő feladatnál –, add át az apiKey értéket a híváson. Az adott kérésre lecseréli az Authorization fejlécet, és semmit nem hagy maga után a kliensen.
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 })A tempMail körén kívül minden metódus az utolsó argumentumában fogadja, a signal mellett, listáknál pedig ugyanabban az objektumban, mint a szűrők. A kérés elküldése előtt ellenőrizzük, ugyanazzal a szabállyal, amelyet a konstruktor használ, így az elgépelés Error kivételt dob a { apiKey } on this call megnevezésével, nem pedig 401-et egy olyan hitelesítő adatról, amelyet utána meg kell keresned. Az újrapróbált hívás megtartja a kapott kulcsot.
A signal egy AbortSignal. A megszakítása leállítja a kérést, és a mögötte várakozó újrapróbálkozást is.
Az openemail.mode azt a kulcsot írja le, amellyel a kliens LÉTREJÖTT, és nem követi a felülírást. Ha egy kliens több kulcsot szolgál ki, nincs egyetlen jelenthető mód, ezért az átadott kulcsból olvasd ki.
Böngészőből
A kliens böngészőben nem hajlandó elindulni, és még azelőtt kivételt dob, hogy bármilyen kérés kimenne. A weboldalon lévő kulcs publikált kulcs: bárki, aki megnyitja a fejlesztői eszközöket, küldhet vele levelet és olvashatja a postafiókot. Hívd inkább kiszolgálóról, serverless függvényből vagy szkriptből.
Az eldobható postafiókok a kivétel. A createTempMail() olyan klienst épít, amely nem hordoz API-kulcsot, így weboldalon is biztonságos. Névtelenül hoz létre postafiókokat, és minden olvasáskor a create által visszaadott tokent küldi – akár hívásonként inboxToken néven, akár egyszer a createTempMail({ inboxToken }) hívással.
import { createTempMail } from '@openemail/sdk' const tempMail = createTempMail() const inbox = await tempMail.create()const { items, expiresAt } = await tempMail.listMessages(inbox.id, { inboxToken: inbox.token })Ha mégis átadod a dangerouslyAllowBrowser: true beállítást, az API a CORS-előellenőrzésen pontosan a Content-Type, az Authorization és az Idempotency-Key fejlécet engedi át, így a headers beállításban megadott további fejléc nem a kérést, hanem az előellenőrzést buktatja el – arról pedig, amit a böngésző ilyenkor jelent, semmi hasznosat nem lehet megtudni.