Konfiguration
Drei Wege, einen Client zu erzeugen, alle Optionen und was er ablehnt, bevor eine Anfrage gesendet wird.
Optionen
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_…')| Einstiegspunkt | Was Sie damit erhalten |
|---|---|
| `init(options)` | Konfiguriert den gemeinsamen Client und gibt ihn zurück. openemail ist ab diesem Zeitpunkt in jedem Modul dieser Client, und alles, was Sie weglassen, wird aus der Umgebung gelesen. |
| `openemail` | Der gemeinsame Client. Wird er vor init verwendet, baut er sich beim ersten Aufruf aus OPENEMAIL_API_KEY und OPENEMAIL_BASE_URL selbst auf. |
| `createOpenEmail(options)` | Ein separater Client mit demselben Rückgriff auf die Umgebung, für einen zweiten Schlüssel neben dem gemeinsamen oder um die Instanz zu erzeugen, die Ihr eigenes Modul exportiert. createClient ist dieselbe Funktion unter dem Namen, den das envless SDK verwendet. |
| `new OpenEmail(options)` oder `new OpenEmail(apiKey)` | Ein separater Client, der genau aus dem gebaut wird, was Sie übergeben. Er liest keine Umgebung, daher ist apiKey erforderlich. Zugleich der Default-Export. |
init({ apiKey: 'oe_live_…', baseUrl: 'https://api.openemail.uk', timeoutMs: 30_000, maxRetries: 2, fetch: myFetch, headers: {}, userAgent: 'billing-service/1.4', disableUpdateNotice: true,})| Option | Standard | Hinweise |
|---|---|---|
| `apiKey` | OPENEMAIL_API_KEY | Wird von init und createOpenEmail aus der Umgebung gelesen. Muss mit oe_live_ oder oe_test_ beginnen. |
| `baseUrl` | https://api.openemail.uk | Oder OPENEMAIL_BASE_URL. Ein abschließender Schrägstrich wird entfernt, und init und createOpenEmail setzen https:// vor einen blanken Host bzw. http:// vor localhost. |
| `timeoutMs` | 30000 | Pro Versuch, nicht pro Aufruf. Umfasst das Lesen des Bodys, nicht nur der Header. 0 deaktiviert ihn. |
| `maxRetries` | 2 | Zusätzliche Versuche nach dem ersten, bei Aufrufen, die sich gefahrlos wiederholen lassen. Wird am Client gesetzt, nicht pro Aufruf. |
| `fetch` | das globale | Wird für Sie gebunden. Übergeben Sie eine eigene Funktion für einen Proxy, ein Worker-Binding oder ein Test-Double. |
| `headers` | {} | Werden bei jeder Anfrage gesendet. |
| `userAgent` | openemail-sdk/<version> | Wird aus jeder Laufzeitumgebung gesendet, außer aus einem Browser, der das Setzen nicht erlaubt. |
| `disableUpdateNotice` | false | Überspringt die einmal pro Prozess erfolgende Prüfung auf eine neuere Version auf npm. Die Prüfung läuft nur, wenn die Ausgabe an ein Terminal geht, und OPENEMAIL_DISABLE_UPDATE_NOTICE schaltet sie ebenfalls ab. |
| `dangerouslyAllowBrowser` | false | Erlaubt dem Client den Start dort, wo window und document existieren. Gedacht für ein Test-Harness, das sie definiert, nicht für eine Seite. |
Was er vor dem Senden ablehnt
Diese werfen einen einfachen Error an genau der Zeile, die den falschen Wert enthielt, statt beim ersten Versand als verwirrender Fehler aufzutauchen. Die Meldung nennt, was falsch war und was stattdessen zu übergeben ist.
| Abgelehnt | Warum |
|---|---|
| Gar kein Schlüssel | Weder apiKey noch OPENEMAIL_API_KEY wurde gesetzt, es gibt also nichts, womit authentifiziert werden könnte. |
| Ein Session-Cookie oder Session-Token | Nur oe_live_ und oe_test_ authentifizieren hier, und die API sieht es genauso. Die Prüfung ist ein Präfix und nichts weiter, ein widerrufener Schlüssel scheitert daher erst auf der Leitung. |
| Eine `baseUrl`, die keine http- oder https-URL ist | Anderes lässt sich nicht abrufen, und eine ungeprüfte URL würde später als blanker TypeError an ganz anderer Stelle scheitern. |
| Ein Browser | Der Schlüssel wäre für jeden lesbar, der die Entwicklertools öffnet. Siehe den Abschnitt unten. |
| Nirgends ein `fetch` | Übergeben Sie eines als fetch oder verwenden Sie Node 20+. |
| Eine leere oder nur aus Punkten bestehende id bei einer beliebigen Methode | Wird beim Aufruf der Methode geworfen. Ein Pfadsegment aus Punkten wird von jedem URL-Parser entfernt, die Anfrage träfe also einen anderen Endpunkt. |
Es gibt keine Option testMode und wird auch keine geben. Das Schlüsselschema ist Teil der Zugangsdaten und kein Hinweis, der Modus ist also eine Eigenschaft des Schlüssels. openemail.mode liest das Präfix und entscheidet nichts.
Ein Client, mehrere Schlüssel
Erzeugen Sie den Client einmal und teilen Sie ihn. Eine frische Instanz pro Anfrage wirft das fetch-Binding und die Konfiguration ohne Gegenwert weg, und kein Zustand darauf ist aufruferspezifisch.
Für den Fall, der sonst eine Instanz pro Schlüssel erzwingen würde, etwa einen Job, der im Namen mehrerer Workspaces sendet, übergeben Sie apiKey beim Aufruf. Er ersetzt den Authorization-Header für diese Anfrage und hinterlässt nichts am Client.
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 })Jede Methode außerhalb von tempMail nimmt ihn im letzten Argument entgegen, neben signal, und bei einer Liste im selben Objekt wie die Filter. Er wird vor dem Senden der Anfrage geprüft, nach derselben Regel wie im Konstruktor, ein Tippfehler wirft daher einen Error, der { apiKey } on this call nennt, statt eines 401 zu Zugangsdaten, die Sie erst suchen müssten. Ein wiederholter Aufruf behält den Schlüssel, den er erhalten hat.
signal ist ein AbortSignal. Ein Abbruch stoppt die Anfrage und jeden dahinter wartenden Wiederholungsversuch.
openemail.mode beschreibt den Schlüssel, mit dem der Client KONSTRUIERT wurde, und folgt keiner Überschreibung. Sobald ein Client mehrere Schlüssel bedient, gibt es keinen einzelnen Modus zu melden, lesen Sie ihn daher am übergebenen Schlüssel ab.
Aus einem Browser
Der Client verweigert den Start in einem Browser und wirft, bevor eine Anfrage hinausgeht. Ein Schlüssel in einer Seite ist ein veröffentlichter Schlüssel: Er kann Mail senden und das Postfach lesen, für jeden, der die Entwicklertools öffnet. Rufen Sie ihn stattdessen von einem Server, einer Serverless-Funktion oder einem Skript aus auf.
Wegwerf-Posteingänge sind die Ausnahme. createTempMail() erzeugt einen Client ohne API-Schlüssel, er ist daher in einer Seite unbedenklich. Er legt Posteingänge anonym an, und jeder Lesezugriff sendet das von create zurückgegebene Token, entweder pro Aufruf als inboxToken oder einmalig als createTempMail({ inboxToken }).
import { createTempMail } from '@openemail/sdk' const tempMail = createTempMail() const inbox = await tempMail.create()const { items, expiresAt } = await tempMail.listMessages(inbox.id, { inboxToken: inbox.token })Wenn Sie dennoch dangerouslyAllowBrowser: true übergeben: Die API lässt durch ihren CORS-Preflight genau Content-Type, Authorization und Idempotency-Key zu, ein zusätzlicher Header in headers lässt daher den Preflight scheitern und nicht die Anfrage, und was ein Browser dazu meldet, sagt nichts Brauchbares aus.