SDK

Konfigurace

Tři způsoby, jak sestavit klienta, všechny volby a to, co odmítne dřív, než se odešle požadavek.

Volby

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

Vstupní bod	Co vám dá
`init(options)`	Nakonfiguruje sdíleného klienta a vrátí ho. `openemail` je od té chvíle tímto klientem, a to v každém modulu, a cokoli vynecháte, se načte z prostředí.
`openemail`	Sdílený klient. Použitý před `init` se při prvním volání sestaví sám z `OPENEMAIL_API_KEY` a `OPENEMAIL_BASE_URL`.
`createOpenEmail(options)`	Samostatný klient se stejným záložním čtením z prostředí, pro druhý klíč vedle sdíleného, nebo pro sestavení instance, kterou exportuje váš vlastní modul. `createClient` je tatáž funkce pod názvem, který používá SDK envless.
`new OpenEmail(options)` nebo `new OpenEmail(apiKey)`	Samostatný klient sestavený přesně z toho, co předáte. Nečte prostředí, takže `apiKey` je povinný. Je zároveň výchozím exportem.

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

Volba	Výchozí hodnota	Poznámky
`apiKey`	`OPENEMAIL_API_KEY`	Čtou ho z prostředí `init` a `createOpenEmail`. Musí začínat `oe_live_` nebo `oe_test_`.
`baseUrl`	`https://api.openemail.uk`	Nebo `OPENEMAIL_BASE_URL`. Koncové lomítko se ořízne a `init` a `createOpenEmail` předřadí samotnému hostiteli `https://`, nebo `http://` před localhost.
`timeoutMs`	30000	Na pokus, ne na volání. Zahrnuje i čtení těla, nejen hlaviček. 0 ho vypne.
`maxRetries`	2	Další pokusy po prvním, u volání, která je bezpečné opakovat. Nastavuje se na klientovi, ne u jednotlivých volání.
`fetch`	globální	Naváže se za vás. Vlastní předejte kvůli proxy, bindingu ve Workeru nebo testovacímu dvojníkovi.
`headers`	`{}`	Posílají se s každým požadavkem.
`userAgent`	`openemail-sdk/<version>`	Posílá se z každého runtime kromě prohlížeče, který jeho nastavení nedovoluje.
`disableUpdateNotice`	false	Přeskočí kontrolu novější verze na npm, která probíhá jednou za proces. Kontrola běží jen tehdy, když výstup jde do terminálu, a vypne ji i `OPENEMAIL_DISABLE_UPDATE_NOTICE`.
`dangerouslyAllowBrowser`	false	Dovolí klientovi nastartovat tam, kde existují `window` a `document`. Je určená pro testovací prostředí, které je definuje, ne pro webovou stránku.

Co odmítne ještě před odesláním

Tyto případy vyhodí obyčejný Error na řádku, který obsahoval špatnou hodnotu, místo aby se projevily jako matoucí selhání při vašem prvním odeslání. Zpráva říká, co bylo špatně a co předat místo toho.

Odmítnuto	Proč
Vůbec žádný klíč	Nebyl nastaven ani `apiKey`, ani `OPENEMAIL_API_KEY`, takže není čím se autentizovat.
Session cookie nebo session token	Autentizují tu jen `oe_live_` a `oe_test_` a API to říká také. Kontrola je jen předpona a nic víc, takže odvolaný klíč stále selže až na drátě.
`baseUrl`, které není http ani https URL	Nic jiného nelze načíst a neověřená hodnota by selhala až později jako holý `TypeError` odněkud úplně jinud.
Prohlížeč	Klíč by si mohl přečíst každý, kdo otevře vývojářské nástroje. Viz sekce níže.
Nikde žádný `fetch`	Předejte vlastní jako `fetch`, nebo běžte na Node 20+.
Prázdné id nebo id ze samých teček u kterékoli metody	Vyhodí se při zavolání metody. Segment cesty tvořený tečkami odstraní každý parser URL, takže by požadavek dorazil na jiný endpoint.

Volba testMode neexistuje a existovat nebude. Schéma klíče je součástí přihlašovacího údaje, ne nápovědou, takže režim je vlastností klíče. openemail.mode čte předponu a o ničem nerozhoduje.

Jeden klient, několik klíčů

Klienta sestavte jednou a sdílejte ho. Nová instance pro každý požadavek zbytečně zahazuje navázaný fetch a konfiguraci a žádný stav na ní není vázaný na konkrétního volajícího.

Pro případ, který by jinak vynutil jednu instanci na klíč, například úloha odesílající za několik pracovních prostorů, předejte apiKey přímo ve volání. Pro daný požadavek nahradí hlavičku Authorization a na klientovi po sobě nic nenechá.

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

Každá metoda mimo tempMail ho přijímá ve svém posledním argumentu, vedle signal, a u výpisů je to tentýž objekt jako filtry. Kontroluje se dřív, než se požadavek odešle, podle stejného pravidla jako v konstruktoru, takže překlep vyhodí Error zmiňující { apiKey } on this call, a ne 401 o přihlašovacím údaji, který pak musíte jít hledat. Opakované volání si ponechá klíč, který dostalo.

signal je AbortSignal. Jeho přerušení zastaví požadavek i jakýkoli opakovaný pokus, který za ním čeká.

openemail.mode popisuje klíč, se kterým byl klient SESTAVEN, a nepřebírá přepsání na úrovni volání. Jakmile jeden klient obsluhuje několik klíčů, není jediný režim, který by šlo hlásit, takže si ho přečtěte z klíče, který jste předali.

Z prohlížeče

Klient odmítne nastartovat v prohlížeči a vyhodí výjimku dřív, než odejde jakýkoli požadavek. Klíč ve stránce je klíč, který jste zveřejnili: komukoli, kdo otevře vývojářské nástroje, umožní odesílat poštu a číst schránku. Volejte ho raději ze serveru, ze serverless funkce nebo ze skriptu.

Výjimkou jsou jednorázové schránky. createTempMail() sestaví klienta, který nenese žádný API klíč, takže je ve stránce bezpečný. Schránky vytváří anonymně a každé čtení posílá token, který vrátilo create, buď u jednotlivého volání jako inboxToken, nebo jednou jako 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 })

Pokud přesto předáte dangerouslyAllowBrowser: true, API propouští svým CORS preflightem přesně Content-Type, Authorization a Idempotency-Key, takže hlavička navíc v headers neshodí požadavek, ale preflight, a to, co o tom prohlížeč hlásí, neřekne nic užitečného.