SDK

Configuración

Tres formas de construir un cliente, todas las opciones y lo que rechaza antes de enviar una solicitud.

Opciones

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

Punto de entrada	Qué te ofrece
`init(options)`	Configura el cliente compartido y lo devuelve. A partir de ese momento, `openemail` es ese cliente en todos los módulos, y todo lo que omitas se lee del entorno.
`openemail`	El cliente compartido. Si se usa antes de `init`, se construye a partir de `OPENEMAIL_API_KEY` y `OPENEMAIL_BASE_URL` en la primera llamada.
`createOpenEmail(options)`	Un cliente independiente con el mismo respaldo desde el entorno, para una segunda clave junto a la compartida, o para construir la instancia que exporta tu propio módulo. `createClient` es la misma función con el nombre que usa el SDK de envless.
`new OpenEmail(options)` o `new OpenEmail(apiKey)`	Un cliente independiente construido exactamente con lo que le pasas. No lee el entorno, así que `apiKey` es obligatorio. También es la exportación por defecto.

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ón	Valor por defecto	Notas
`apiKey`	`OPENEMAIL_API_KEY`	`init` y `createOpenEmail` la leen del entorno. Debe empezar por `oe_live_` u `oe_test_`.
`baseUrl`	`https://api.openemail.uk`	O `OPENEMAIL_BASE_URL`. La barra final se elimina, e `init` y `createOpenEmail` anteponen `https://` a un host sin esquema, o `http://` a localhost.
`timeoutMs`	30000	Por intento, no por llamada. Cubre la lectura del cuerpo, no solo de las cabeceras. 0 lo desactiva.
`maxRetries`	2	Intentos adicionales después del primero, en llamadas que se pueden repetir sin riesgo. Se configura en el cliente, no por llamada.
`fetch`	el global	Se enlaza por ti. Pasa el tuyo para un proxy, un binding de Worker o un doble de prueba.
`headers`	`{}`	Se envían en cada solicitud.
`userAgent`	`openemail-sdk/<version>`	Se envía desde todos los entornos de ejecución salvo un navegador, que no permite establecerlo.
`disableUpdateNotice`	false	Omite la comprobación, una vez por proceso, de si hay una versión más reciente en npm. La comprobación solo se ejecuta cuando la salida va a una terminal, y `OPENEMAIL_DISABLE_UPDATE_NOTICE` también la desactiva.
`dangerouslyAllowBrowser`	false	Permite que el cliente se inicie donde existen `window` y `document`. Está pensado para un entorno de pruebas que los define, no para una página.

Lo que rechaza antes de enviar

Estos lanzan un Error simple desde la línea que contenía el valor incorrecto, en lugar de aparecer como un fallo confuso en tu primer envío. El mensaje indica qué estaba mal y qué pasar en su lugar.

Rechazado	Por qué
Ninguna clave	No se definió ni `apiKey` ni `OPENEMAIL_API_KEY`, así que no hay nada con lo que autenticarse.
Una cookie de sesión o un token de sesión	Aquí solo autentican `oe_live_` y `oe_test_`, y la API lo confirma. La comprobación es un prefijo y nada más, así que una clave revocada sigue fallando en la red.
Un `baseUrl` que no es una URL http o https	No se puede hacer fetch de nada más, y uno sin validar fallaría más tarde como un `TypeError` en bruto desde un lugar completamente distinto.
Un navegador	Cualquiera que abra las herramientas de desarrollo podría leer la clave. Consulta la sección siguiente.
No hay `fetch` en ninguna parte	Pasa uno como `fetch`, o ejecuta en Node 20+.
Un id vacío o compuesto solo de puntos en cualquier método	Se lanza al llamar al método. Todos los analizadores de URL eliminan un segmento de ruta formado por puntos, así que la solicitud llegaría a otro endpoint.

No existe una opción testMode ni la habrá. El esquema de la clave forma parte de la credencial en lugar de ser una pista, así que el modo es una propiedad de la clave. openemail.mode lee el prefijo y no decide nada.

Un cliente, varias claves

Construye el cliente una vez y compártelo. Una instancia nueva por solicitud desecha el enlace de fetch y la configuración sin ganar nada, y ninguno de sus estados es propio de cada llamante.

Para el caso que de otro modo obligaría a una instancia por clave, como un trabajo que envía en nombre de varios espacios de trabajo, pasa apiKey en la llamada. Sustituye la cabecera Authorization de esa solicitud y no deja nada en el cliente.

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

Todos los métodos fuera de tempMail la aceptan en su último argumento, junto a signal, y en una lista ese es el mismo objeto que los filtros. Se comprueba antes de enviar la solicitud, con la misma regla que usa el constructor, así que una errata lanza un Error que menciona { apiKey } on this call en lugar de un 401 sobre una credencial que luego tienes que ir a buscar. Una llamada reintentada conserva la clave que se le dio.

signal es un AbortSignal. Abortarlo detiene la solicitud y cualquier reintento que esté esperando detrás.

openemail.mode describe la clave con la que se CONSTRUYÓ el cliente y no sigue a una sustitución puntual. En cuanto un cliente sirve a varias claves no hay un único modo que informar, así que dedúcelo de la clave que pasaste.

Desde un navegador

El cliente se niega a iniciarse en un navegador y lanza un error antes de que salga ninguna solicitud. Una clave en una página es una clave que has publicado: puede enviar correo y leer el buzón para cualquiera que abra las herramientas de desarrollo. Llámalo desde un servidor, una función serverless o un script.

Los buzones desechables son la excepción. createTempMail() construye un cliente que no lleva ninguna clave de API, así que es seguro en una página. Crea buzones de forma anónima, y cada lectura envía el token que devolvió create, bien por llamada como inboxToken, bien una sola vez como 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 aun así pasas dangerouslyAllowBrowser: true, la API admite exactamente Content-Type, Authorization e Idempotency-Key en su preflight de CORS, de modo que una cabecera extra en headers hace fallar el preflight y no la solicitud, y lo que un navegador informa en ese caso no dice nada útil.