SDK

Configuração

Três formas de construir um cliente, todas as opções e o que ele recusa antes de um pedido ser enviado.

Opções

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

Ponto de entrada	O que obtém
`init(options)`	Configura o cliente partilhado e devolve-o. A partir daí, `openemail` é esse cliente em todos os módulos, e tudo o que omitir é lido do ambiente.
`openemail`	O cliente partilhado. Se for usado antes de `init`, constrói-se a si próprio a partir de `OPENEMAIL_API_KEY` e `OPENEMAIL_BASE_URL` na primeira chamada.
`createOpenEmail(options)`	Um cliente separado com o mesmo recurso ao ambiente, para uma segunda chave ao lado da partilhada, ou para construir a instância que o seu próprio módulo exporta. `createClient` é a mesma função com o nome que o SDK do envless usa.
`new OpenEmail(options)` ou `new OpenEmail(apiKey)`	Um cliente separado construído exatamente a partir do que passar. Não lê o ambiente, pelo que `apiKey` é obrigatório. É também a exportação predefinida.

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

Opção	Predefinição	Notas
`apiKey`	`OPENEMAIL_API_KEY`	Lida do ambiente por `init` e `createOpenEmail`. Tem de começar por `oe_live_` ou `oe_test_`.
`baseUrl`	`https://api.openemail.uk`	Ou `OPENEMAIL_BASE_URL`. Uma barra final é removida, e `init` e `createOpenEmail` acrescentam `https://` antes de um host simples, ou `http://` antes de localhost.
`timeoutMs`	30000	Por tentativa, não por chamada. Abrange a leitura do corpo, não só dos cabeçalhos. 0 desativa-o.
`maxRetries`	2	Tentativas adicionais após a primeira, em chamadas que é seguro repetir. Define-se no cliente, não por chamada.
`fetch`	o global	Associado automaticamente. Passe um para um proxy, um binding de Worker ou um duplo de teste.
`headers`	`{}`	Enviados em todos os pedidos.
`userAgent`	`openemail-sdk/<version>`	Enviado a partir de todos os runtimes exceto um navegador, que não permite defini-lo.
`disableUpdateNotice`	false	Ignora a verificação, feita uma vez por processo, de uma versão mais recente no npm. A verificação só é executada quando a saída vai para um terminal, e `OPENEMAIL_DISABLE_UPDATE_NOTICE` também a desativa.
`dangerouslyAllowBrowser`	false	Permite que o cliente arranque onde `window` e `document` existem. Destina-se a um ambiente de testes que os define, não a uma página.

O que recusa antes de enviar

Estes casos lançam um Error simples a partir da linha que continha o valor errado, em vez de surgirem como uma falha confusa no seu primeiro envio. A mensagem indica o que estava errado e o que passar em vez disso.

Recusado	Porquê
Nenhuma chave	Nem `apiKey` nem `OPENEMAIL_API_KEY` foram definidos, pelo que não há nada com que autenticar.
Um cookie de sessão ou um token de sessão	Só `oe_live_` e `oe_test_` autenticam aqui, e a API também o diz. A verificação é apenas de prefixo, pelo que uma chave revogada só é rejeitada quando o pedido é enviado.
Um `baseUrl` que não é um URL http ou https	Não é possível fazer fetch de mais nada, e um valor não validado falharia mais tarde como um `TypeError` em bruto vindo de um sítio completamente diferente.
Um navegador	A chave ficaria legível para qualquer pessoa que abrisse as devtools. Consulte a secção abaixo.
Nenhum `fetch` disponível	Passe um como `fetch` ou execute em Node 20+.
Um id vazio ou composto só por pontos em qualquer método	Lançado quando o método é chamado. Um segmento de caminho feito de pontos é removido por qualquer parser de URL, pelo que o pedido chegaria a um endpoint diferente.

Não existe uma opção testMode nem vai existir. O esquema da chave faz parte da credencial e não é uma mera indicação, pelo que o modo é uma propriedade da chave. openemail.mode lê o prefixo e não decide nada.

Um cliente, várias chaves

Construa o cliente uma vez e partilhe-o. Uma nova instância por pedido deita fora a associação do fetch e a configuração sem qualquer ganho, e nenhum do estado que contém é específico de quem chama.

No caso que, de outro modo, obrigaria a uma instância por chave, como uma tarefa que envia em nome de vários espaços de trabalho, passe apiKey na chamada. Substitui o cabeçalho Authorization para esse pedido e não deixa nada no 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 os métodos fora de tempMail recebem-no no último argumento, ao lado de signal, e numa listagem esse é o mesmo objeto dos filtros. É verificado antes de o pedido ser enviado, pela mesma regra que o construtor usa, pelo que um erro de escrita lança um Error que refere { apiKey } on this call em vez de um 401 sobre uma credencial que depois tem de ir procurar. Uma chamada repetida mantém a chave que lhe foi dada.

signal é um AbortSignal. Abortá-lo interrompe o pedido e qualquer nova tentativa que esteja à espera a seguir.

openemail.mode descreve a chave com que o cliente foi CONSTRUÍDO e não acompanha uma substituição. Quando um cliente serve várias chaves, não há um modo único a indicar, por isso leia-o a partir da chave que passou.

A partir de um navegador

O cliente recusa-se a arrancar num navegador e lança um erro antes de qualquer pedido sair. Uma chave numa página é uma chave que publicou: pode enviar correio e ler a caixa de correio para qualquer pessoa que abra as devtools. Chame-o antes a partir de um servidor, de uma função serverless ou de um script.

As caixas de entrada descartáveis são a exceção. createTempMail() constrói um cliente que não transporta nenhuma chave de API, pelo que é seguro numa página. Cria caixas de entrada de forma anónima, e cada leitura envia o token que create devolveu, seja por chamada como inboxToken ou uma única 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 })

Se mesmo assim passar dangerouslyAllowBrowser: true, a API permite exatamente Content-Type, Authorization e Idempotency-Key no seu preflight CORS, pelo que um cabeçalho extra em headers faz falhar o preflight e não o pedido, e o que o navegador reporta nesse caso não diz nada de útil.