Konfiguracja
Trzy sposoby na zbudowanie klienta, wszystkie opcje i to, co odrzuca, zanim wyśle żądanie.
Opcje
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_…')| Punkt wejścia | Co daje |
|---|---|
| `init(options)` | Konfiguruje współdzielonego klienta i go zwraca. openemail jest od tej chwili tym klientem, w każdym module, a wszystko, co pominiesz, jest czytane ze środowiska. |
| `openemail` | Współdzielony klient. Użyty przed init, buduje się z OPENEMAIL_API_KEY i OPENEMAIL_BASE_URL przy pierwszym wywołaniu. |
| `createOpenEmail(options)` | Osobny klient z tym samym fallbackiem na środowisko, na drugi klucz obok współdzielonego albo do zbudowania instancji, którą eksportuje Twój własny moduł. createClient to ta sama funkcja pod nazwą używaną przez SDK envless. |
| `new OpenEmail(options)` lub `new OpenEmail(apiKey)` | Osobny klient zbudowany dokładnie z tego, co przekażesz. Nie czyta środowiska, więc apiKey jest wymagany. To także eksport domyślny. |
init({ apiKey: 'oe_live_…', baseUrl: 'https://api.openemail.uk', timeoutMs: 30_000, maxRetries: 2, fetch: myFetch, headers: {}, userAgent: 'billing-service/1.4', disableUpdateNotice: true,})| Opcja | Domyślnie | Uwagi |
|---|---|---|
| `apiKey` | OPENEMAIL_API_KEY | Czytany ze środowiska przez init i createOpenEmail. Musi zaczynać się od oe_live_ lub oe_test_. |
| `baseUrl` | https://api.openemail.uk | Albo OPENEMAIL_BASE_URL. Końcowy ukośnik jest obcinany, a init i createOpenEmail dostawiają https:// przed samym hostem lub http:// przed localhostem. |
| `timeoutMs` | 30000 | Na próbę, nie na wywołanie. Obejmuje odczyt treści, nie tylko nagłówków. 0 go wyłącza. |
| `maxRetries` | 2 | Dodatkowe próby po pierwszej, na wywołaniach, które można bezpiecznie powtórzyć. Ustawiane na kliencie, nie per wywołanie. |
| `fetch` | globalny | Powiązany za Ciebie. Przekaż własny dla proxy, powiązania Workera albo atrapy testowej. |
| `headers` | {} | Wysyłane przy każdym żądaniu. |
| `userAgent` | openemail-sdk/<version> | Wysyłany z każdego środowiska uruchomieniowego poza przeglądarką, która nie pozwala go ustawić. |
| `disableUpdateNotice` | false | Pomija wykonywane raz na proces sprawdzenie, czy w npm jest nowsza wersja. Sprawdzenie działa tylko wtedy, gdy wyjście idzie do terminala, a OPENEMAIL_DISABLE_UPDATE_NOTICE też je wyłącza. |
| `dangerouslyAllowBrowser` | false | Pozwala klientowi wystartować tam, gdzie istnieją window i document. Przeznaczone dla środowiska testowego, które je definiuje, a nie dla strony. |
Co odrzuca przed wysłaniem
Rzucają zwykły Error z tej linii, w której była zła wartość, zamiast wypływać jako mylący błąd przy pierwszej wysyłce. Komunikat mówi, co było nie tak i co przekazać zamiast tego.
| Odrzucone | Dlaczego |
|---|---|
| Brak jakiegokolwiek klucza | Nie ustawiono ani apiKey, ani OPENEMAIL_API_KEY, więc nie ma czym się uwierzytelnić. |
| Ciasteczko sesji albo token sesji | Tutaj uwierzytelniają wyłącznie oe_live_ i oe_test_, i API mówi to samo. Sprawdzenie dotyczy tylko prefiksu, więc unieważniony klucz i tak polegnie na łączu. |
| `baseUrl`, które nie jest adresem http ani https | Nic innego nie da się pobrać, a niezweryfikowany adres poległby później jako surowy TypeError z zupełnie innego miejsca. |
| Przeglądarka | Klucz byłby czytelny dla każdego, kto otworzy narzędzia deweloperskie. Zobacz sekcję poniżej. |
| Brak `fetch` gdziekolwiek | Przekaż własny jako fetch albo uruchom na Node 20+. |
| Pusty identyfikator albo złożony z samych kropek w dowolnej metodzie | Rzucane w momencie wywołania metody. Segment ścieżki złożony z kropek jest usuwany przez każdy parser adresów, więc żądanie trafiłoby do innego endpointu. |
Nie ma opcji testMode i nie będzie. Schemat klucza jest częścią poświadczenia, a nie podpowiedzią, więc tryb jest właściwością klucza. openemail.mode czyta prefiks i o niczym nie decyduje.
Jeden klient, kilka kluczy
Zbuduj klienta raz i współdziel go. Świeża instancja na każde żądanie wyrzuca powiązanie fetch i konfigurację bez żadnego zysku, a żaden ze stanów na niej nie jest per wywołujący.
W przypadku, który inaczej wymuszałby jedną instancję na klucz, na przykład zadania wysyłającego w imieniu kilku przestrzeni roboczych, przekaż apiKey w wywołaniu. Zastępuje nagłówek Authorization dla tego jednego żądania i nie zostawia niczego na kliencie.
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żda metoda poza tempMail przyjmuje go w ostatnim argumencie, obok signal, a na liście jest to ten sam obiekt co filtry. Jest sprawdzany przed wysłaniem żądania, tą samą regułą, której używa konstruktor, więc literówka rzuca Error nazywający { apiKey } on this call zamiast 401 o poświadczeniu, którego potem trzeba szukać. Ponowione wywołanie zachowuje klucz, który dostało.
signal to AbortSignal. Jego przerwanie zatrzymuje żądanie oraz każde ponowienie czekające za nim.
openemail.mode opisuje klucz, którym klienta SKONSTRUOWANO, i nie podąża za nadpisaniem. Gdy jeden klient obsługuje kilka kluczy, nie ma jednego trybu do zaraportowania, więc odczytaj go z klucza, który przekazałeś.
Z przeglądarki
Klient odmawia startu w przeglądarce i rzuca wyjątek, zanim wyjdzie jakiekolwiek żądanie. Klucz na stronie to klucz opublikowany: może wysyłać pocztę i czytać skrzynkę każdemu, kto otworzy narzędzia deweloperskie. Wywołuj go zamiast tego z serwera, funkcji serverless albo skryptu.
Jednorazowe skrzynki są wyjątkiem. createTempMail() buduje klienta, który nie niesie klucza API, więc jest bezpieczny na stronie. Tworzy skrzynki anonimowo, a każdy odczyt wysyła token zwrócony przez create, albo per wywołanie jako inboxToken, albo raz jako createTempMail({ inboxToken }).
import { createTempMail } from '@openemail/sdk' const tempMail = createTempMail() const inbox = await tempMail.create()const { items, expiresAt } = await tempMail.listMessages(inbox.id, { inboxToken: inbox.token })Tam, gdzie mimo wszystko przekażesz dangerouslyAllowBrowser: true, API przepuszcza przez swój preflight CORS dokładnie Content-Type, Authorization i Idempotency-Key, więc dodatkowy nagłówek w headers wywraca preflight, a nie żądanie, a to, co przeglądarka o tym raportuje, nie mówi nic użytecznego.