SDK

Configuració

Tres maneres de construir un client, totes les opcions i què rebutja abans d'enviar cap sol·licitud.

Opcions

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

Punt d'entrada	Què t'ofereix
`init(options)`	Configura el client compartit i el retorna. A partir d'aleshores `openemail` és aquest client, a tots els mòduls, i tot allò que ometis es llegeix de l'entorn.
`openemail`	El client compartit. Si es fa servir abans d'`init`, es construeix a si mateix a partir d'`OPENEMAIL_API_KEY` i `OPENEMAIL_BASE_URL` en la primera crida.
`createOpenEmail(options)`	Un client separat amb el mateix recurs a l'entorn, per a una segona clau al costat de la compartida, o per construir la instància que exporta el teu propi mòdul. `createClient` és la mateixa funció amb el nom que fa servir l'SDK d'envless.
`new OpenEmail(options)` o `new OpenEmail(apiKey)`	Un client separat construït exactament amb el que li passes. No llegeix cap entorn, així que `apiKey` és obligatori. També és l'export per defecte.

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

Opció	Per defecte	Notes
`apiKey`	`OPENEMAIL_API_KEY`	`init` i `createOpenEmail` la llegeixen de l'entorn. Ha de començar per `oe_live_` o `oe_test_`.
`baseUrl`	`https://api.openemail.uk`	O bé `OPENEMAIL_BASE_URL`. La barra final s'elimina, i `init` i `createOpenEmail` posen `https://` davant d'un amfitrió sense esquema, o `http://` davant de localhost.
`timeoutMs`	30000	Per intent, no per crida. Cobreix la lectura del cos, no només la de les capçaleres. 0 el desactiva.
`maxRetries`	2	Intents addicionals després del primer, en crides que es poden repetir sense perill. Es defineix al client, no per crida.
`fetch`	la global	Ja ve enllaçada. Passa'n una per a un proxy, un binding de Worker o un doble de prova.
`headers`	`{}`	S'envien a cada sol·licitud.
`userAgent`	`openemail-sdk/<version>`	S'envia des de tots els entorns d'execució excepte un navegador, que no permet definir-lo.
`disableUpdateNotice`	false	Omet la comprovació, un cop per procés, de si hi ha una versió més nova a npm. La comprovació només s'executa quan la sortida va a un terminal, i `OPENEMAIL_DISABLE_UPDATE_NOTICE` també la desactiva.
`dangerouslyAllowBrowser`	false	Permet que el client arrenqui allà on existeixen `window` i `document`. Pensat per a un arnès de proves que els defineixi, no pas per a una pàgina.

Què rebutja abans d'enviar

Aquests llancen un Error normal des de la línia que contenia el valor incorrecte, en comptes d'aparèixer com una fallada confusa en el teu primer enviament. El missatge diu què estava malament i què cal passar-hi.

Rebutjat	Per què
Cap clau	No s'ha definit ni `apiKey` ni `OPENEMAIL_API_KEY`, així que no hi ha res amb què autenticar-se.
Una galeta de sessió o un testimoni de sessió	Aquí només autentiquen `oe_live_` i `oe_test_`, i l'API també ho diu. La comprovació és un prefix i res més, de manera que una clau revocada continua fallant al cable.
Un `baseUrl` que no és una URL http o https	No es pot fer fetch de res més, i un valor sense validar fallaria més tard com un `TypeError` cru vingut d'un lloc completament diferent.
Un navegador	Qualsevol que obrís les eines de desenvolupament podria llegir la clau. Vegeu la secció de més avall.
No hi ha cap `fetch` enlloc	Passa'n una com a `fetch`, o executa-ho a Node 20+.
Un id buit o fet només de punts en qualsevol mètode	Es llança quan es crida el mètode. Tots els analitzadors d'URL eliminen un segment de camí fet de punts, de manera que la sol·licitud arribaria a un endpoint diferent.

No hi ha cap opció testMode i no n'hi haurà cap. L'esquema de la clau forma part de la credencial i no és una pista, de manera que el mode és una propietat de la clau. openemail.mode llegeix el prefix i no decideix res.

Un client, diverses claus

Construeix el client un sol cop i comparteix-lo. Una instància nova per sol·licitud llença el binding de fetch i la configuració per no res, i cap part del seu estat no és específica de qui fa la crida.

Per al cas que altrament obligaria a tenir una instància per clau, com ara una tasca que envia en nom de diversos espais de treball, passa apiKey a la crida. Substitueix la capçalera Authorization per a aquella sol·licitud i no deixa res al 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 })

Tots els mètodes fora de tempMail el prenen en el seu darrer argument, al costat de signal, i en una llista aquest és el mateix objecte que els filtres. Es comprova abans d'enviar la sol·licitud, amb la mateixa regla que fa servir el constructor, de manera que una errada llança un Error que anomena { apiKey } on this call en comptes d'un 401 sobre una credencial que després has d'anar a buscar. Una crida reintentada conserva la clau que se li va donar.

signal és un AbortSignal. Avortar-lo atura la sol·licitud, i també qualsevol reintent que esperi al darrere.

openemail.mode descriu la clau amb què es va CONSTRUIR el client i no segueix cap substitució. Quan un mateix client serveix diverses claus no hi ha cap mode únic per informar, així que llegeix-lo de la clau que has passat.

Des d'un navegador

El client es nega a arrencar en un navegador i llança un error abans que surti cap sol·licitud. Una clau dins d'una pàgina és una clau que has publicat: pot enviar correu i llegir la bústia per a qualsevol que obri les eines de desenvolupament. Crida'l des d'un servidor, una funció serverless o un script.

Les bústies d'un sol ús són l'excepció. createTempMail() construeix un client que no porta cap clau d'API, de manera que és segur dins d'una pàgina. Crea bústies de manera anònima, i cada lectura envia el testimoni que va retornar create, o bé per crida com a inboxToken o bé un sol cop com a 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 })

Si tot i així passes dangerouslyAllowBrowser: true, l'API només deixa passar Content-Type, Authorization i Idempotency-Key pel seu preflight de CORS, de manera que una capçalera addicional a headers fa fallar el preflight i no pas la sol·licitud, i el que un navegador informa en aquest cas no diu res d'útil.