SDK

Configuratie

Drie manieren om een client te bouwen, elke optie, en wat hij weigert voordat er een verzoek uitgaat.

Opties

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_…')

Ingang	Wat het je geeft
`init(options)`	Configureert de gedeelde client en geeft hem terug. `openemail` is vanaf dat moment die client, in elke module, en alles wat je weglaat wordt uit de omgeving gelezen.
`openemail`	De gedeelde client. Vóór `init` bouwt hij zichzelf bij de eerste aanroep op uit `OPENEMAIL_API_KEY` en `OPENEMAIL_BASE_URL`.
`createOpenEmail(options)`	Een aparte client met dezelfde terugval op de omgeving, voor een tweede sleutel naast de gedeelde, of om de instantie te bouwen die je eigen module exporteert. `createClient` is dezelfde functie onder de naam die de envless-SDK gebruikt.
`new OpenEmail(options)` of `new OpenEmail(apiKey)`	Een aparte client die precies wordt opgebouwd uit wat je meegeeft. Hij leest niets uit de omgeving, dus `apiKey` is verplicht. Tevens de 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,})

Optie	Standaard	Opmerkingen
`apiKey`	`OPENEMAIL_API_KEY`	Door `init` en `createOpenEmail` uit de omgeving gelezen. Moet beginnen met `oe_live_` of `oe_test_`.
`baseUrl`	`https://api.openemail.uk`	Of `OPENEMAIL_BASE_URL`. Een afsluitende slash wordt afgekapt, en `init` en `createOpenEmail` zetten `https://` voor een kale host, of `http://` voor localhost.
`timeoutMs`	30000	Per poging, niet per aanroep. Dekt ook het lezen van de body, niet alleen de headers. 0 schakelt het uit.
`maxRetries`	2	Extra pogingen na de eerste, op aanroepen die veilig te herhalen zijn. Stel dit in op de client, niet per aanroep.
`fetch`	de globale	Voor je gebonden. Geef er een mee voor een proxy, een Worker-binding of een testdubbel.
`headers`	`{}`	Wordt bij elk verzoek meegestuurd.
`userAgent`	`openemail-sdk/<version>`	Wordt vanuit elke runtime meegestuurd behalve een browser, die het niet toestaat deze in te stellen.
`disableUpdateNotice`	false	Slaat de controle op een nieuwere versie op npm over, die één keer per proces gebeurt. De controle draait alleen wanneer de uitvoer naar een terminal gaat, en `OPENEMAIL_DISABLE_UPDATE_NOTICE` schakelt die ook uit.
`dangerouslyAllowBrowser`	false	Laat de client starten waar `window` en `document` bestaan. Bedoeld voor een testharnas dat ze definieert, niet voor een pagina.

Wat het weigert vóór het verzenden

Deze gooien een gewone Error vanaf de regel met de verkeerde waarde erin, in plaats van als een verwarrende fout bij je eerste verzending op te duiken. De melding zegt wat er mis was en wat je in plaats daarvan moet meegeven.

Geweigerd	Waarom
Helemaal geen sleutel	Noch `apiKey` noch `OPENEMAIL_API_KEY` was ingesteld, dus er is niets om mee te authenticeren.
Een sessiecookie of sessietoken	Alleen `oe_live_` en `oe_test_` authenticeren hier, en de API zegt dat ook. De controle is niet meer dan een prefix, dus een ingetrokken sleutel faalt alsnog op de lijn.
Een `baseUrl` die geen http- of https-URL is	Er valt verder niets op te halen, en een ongevalideerde zou later als een kale `TypeError` ergens heel anders vandaan falen.
Een browser	De sleutel zou leesbaar zijn voor iedereen die devtools opent. Zie het onderstaande gedeelte.
Nergens een `fetch`	Geef er een mee als `fetch`, of draai op Node 20+.
Een lege id of een id van alleen punten op welke methode dan ook	Wordt gegooid wanneer de methode wordt aangeroepen. Een padsegment van punten wordt door elke URL-parser verwijderd, dus het verzoek zou bij een ander endpoint uitkomen.

Er is geen testMode-optie en die komt er ook niet. Het sleutelschema maakt deel uit van de credential in plaats van een hint te zijn, dus de modus is een eigenschap van de sleutel. openemail.mode leest de prefix en beslist niets.

Eén client, meerdere sleutels

Bouw de client één keer en deel hem. Een verse instantie per verzoek gooit de fetch-binding en de configuratie voor niets weg, en niets van de state erop is per aanroeper.

Voor het geval dat je anders zou dwingen tot één instantie per sleutel, zoals een job die namens meerdere workspaces verstuurt, geef je apiKey mee op de aanroep. Die vervangt de Authorization-header voor dat verzoek en laat niets achter op de client.

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 })

Elke methode buiten tempMail accepteert hem in het laatste argument, naast signal, en op een lijstaanroep is dat hetzelfde object als de filters. Hij wordt gecontroleerd voordat het verzoek verstuurd wordt, volgens dezelfde regel die de constructor gebruikt, dus een typefout gooit een Error die { apiKey } on this call noemt in plaats van een 401 over een credential die je dan nog moet gaan zoeken. Een herhaalde aanroep houdt de sleutel die hij meekreeg.

signal is een AbortSignal. Hem afbreken stopt het verzoek, en elke herhaling die erachter wacht.

openemail.mode beschrijft de sleutel waarmee de client is GECONSTRUEERD en volgt geen override. Zodra één client meerdere sleutels bedient is er geen enkele modus om te melden, dus lees die af van de sleutel die je meegaf.

Vanuit een browser

De client weigert in een browser te starten en gooit een fout voordat er een verzoek uitgaat. Een sleutel in een pagina is een sleutel die je hebt gepubliceerd: hij kan mail versturen en de mailbox lezen voor iedereen die devtools opent. Roep hem in plaats daarvan aan vanaf een server, een serverless functie of een script.

Wegwerpinboxen zijn de uitzondering. createTempMail() bouwt een client die geen API-sleutel draagt, dus die is veilig in een pagina. Hij maakt anoniem inboxen aan, en elke leesactie stuurt het token mee dat create teruggaf, per aanroep als inboxToken of één keer als 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 })

Waar je toch dangerouslyAllowBrowser: true meegeeft, laat de API via haar CORS-preflight precies Content-Type, Authorization en Idempotency-Key door, dus een extra header in headers laat de preflight falen in plaats van het verzoek, en wat een browser daarover meldt zegt niets nuttigs.