Konfigurimi
Tri mënyra për të ndërtuar një klient, çdo opsion, dhe çfarë refuzon përpara se të dërgohet një kërkesë.
Opsionet
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_…')| Pika e hyrjes | Çfarë ju jep |
|---|---|
| `init(options)` | Konfiguron klientin e përbashkët dhe e kthen atë. openemail është ai klient që nga ai çast, në çdo modul, dhe çdo gjë që lini jashtë lexohet nga mjedisi. |
| `openemail` | Klienti i përbashkët. I përdorur përpara init, ai ndërtohet vetë nga OPENEMAIL_API_KEY dhe OPENEMAIL_BASE_URL në thirrjen e parë. |
| `createOpenEmail(options)` | Një klient i veçantë me të njëjtin fallback nga mjedisi, për një çelës të dytë pranë atij të përbashkët, ose për të ndërtuar instancën që eksporton moduli juaj. createClient është i njëjti funksion nën emrin që përdor SDK-ja envless. |
| `new OpenEmail(options)` ose `new OpenEmail(apiKey)` | Një klient i veçantë i ndërtuar saktësisht nga ajo që i jepni. Ai nuk lexon asnjë mjedis, prandaj apiKey është i detyrueshëm. Është edhe eksporti i parazgjedhur. |
init({ apiKey: 'oe_live_…', baseUrl: 'https://api.openemail.uk', timeoutMs: 30_000, maxRetries: 2, fetch: myFetch, headers: {}, userAgent: 'billing-service/1.4', disableUpdateNotice: true,})| Opsioni | Parazgjedhja | Shënime |
|---|---|---|
| `apiKey` | OPENEMAIL_API_KEY | Lexohet nga mjedisi prej init dhe createOpenEmail. Duhet të fillojë me oe_live_ ose oe_test_. |
| `baseUrl` | https://api.openemail.uk | Ose OPENEMAIL_BASE_URL. Një slash në fund hiqet, dhe init e createOpenEmail vendosin https:// përpara një hosti të zhveshur, ose http:// përpara localhost. |
| `timeoutMs` | 30000 | Për çdo përpjekje, jo për çdo thirrje. Mbulon leximin e trupit, jo vetëm headerët. 0 e çaktivizon. |
| `maxRetries` | 2 | Përpjekje shtesë pas së parës, në thirrjet që janë të sigurta për t'u përsëritur. Caktohet te klienti, jo për çdo thirrje. |
| `fetch` | funksioni global | Lidhet vetë për ju. Jepni një nëse doni një proxy, një binding Worker ose një dublurë testimi. |
| `headers` | {} | Dërgohen në çdo kërkesë. |
| `userAgent` | openemail-sdk/<version> | Dërgohet nga çdo runtime, përveç një shfletuesi, i cili nuk lejon caktimin e tij. |
| `disableUpdateNotice` | false | Anashkalon kontrollin një herë për proces për një version më të ri në npm. Kontrolli kryhet vetëm kur dalja shkon te një terminal, dhe OPENEMAIL_DISABLE_UPDATE_NOTICE e çaktivizon gjithashtu. |
| `dangerouslyAllowBrowser` | false | Lejon nisjen e klientit aty ku ekzistojnë window dhe document. I menduar për një mjedis testimi që i përcakton ato, jo për një faqe. |
Çfarë refuzon para dërgimit
Këto hedhin një Error të thjeshtë nga rreshti që kishte vlerën e gabuar, në vend që të shfaqen si një dështim ngatërrues te dërgimi juaj i parë. Mesazhi thotë çfarë ishte gabim dhe çfarë të jepni në vend të saj.
| Refuzohet | Pse |
|---|---|
| Asnjë çelës fare | As apiKey dhe as OPENEMAIL_API_KEY nuk ishin caktuar, pra nuk ka asgjë me të cilën të autentikohet. |
| Një cookie sesioni ose një token sesioni | Vetëm oe_live_ dhe oe_test_ autentikohen këtu, dhe këtë e thotë edhe API-ja. Kontrolli është thjesht një prefiks dhe asgjë më shumë, prandaj një çelës i revokuar dështon prapë në rrjet. |
| Një `baseUrl` që nuk është URL http ose https | Asgjë tjetër nuk mund të merret, dhe një i pavaliduar do të dështonte më vonë si një TypeError i papërpunuar nga diku krejt tjetër. |
| Një shfletues | Çelësi do të ishte i lexueshëm nga kushdo që hap devtools. Shihni seksionin më poshtë. |
| Asnjë `fetch` askund | Jepni një si fetch, ose ekzekutoni në Node 20+. |
| Një id bosh ose e përbërë vetëm nga pika te çfarëdo metode | Hidhet kur thirret metoda. Një segment shtegu prej pikash hiqet nga çdo parser URL-je, pra kërkesa do të arrinte te një endpoint tjetër. |
Nuk ka opsion testMode dhe nuk do të ketë. Skema e çelësit është pjesë e kredencialit dhe jo një sinjal, pra mënyra është veti e çelësit. openemail.mode lexon prefiksin dhe nuk vendos asgjë.
Një klient, disa çelësa
Ndërtojeni klientin një herë dhe përdorni të njëjtin. Një instancë e re për çdo kërkesë hedh poshtë lidhjen e fetch-it dhe konfigurimin pa asnjë përfitim, dhe asnjë pjesë e gjendjes mbi të nuk është e veçantë për thirrësin.
Për rastin që përndryshe do të detyronte një instancë për çdo çelës, si një punë që dërgon në emër të disa hapësirave pune, jepni apiKey te vetë thirrja. Ai zëvendëson header-in Authorization për atë kërkesë dhe nuk lë asgjë pas te klienti.
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 })Çdo metodë përveç tempMail e pranon te argumenti i saj i fundit, krah signal, dhe te një list ai është i njëjti objekt me filtrat. Kontrollohet para se kërkesa të dërgohet, me të njëjtën rregull që përdor konstruktori, kështu që një gabim shtypi hedh një Error që emërton { apiKey } on this call në vend të një 401-shi për një kredencial që pastaj duhet ta gjeni. Një thirrje e riprovuar e ruan çelësin që iu dha.
signal është një AbortSignal. Ndërprerja e tij e ndal kërkesën, si dhe çdo riprovim që pret pas saj.
openemail.mode përshkruan çelësin me të cilin u NDËRTUA klienti dhe nuk ndjek një mbivendosje. Kur një klient i vetëm u shërben disa çelësave, nuk ka një mënyrë të vetme për të raportuar, prandaj lexojeni atë nga çelësi që dhatë.
Nga një shfletues
Klienti refuzon të niset në një shfletues dhe hedh gabim para se të dalë ndonjë kërkesë. Një çelës në një faqe është një çelës që e keni publikuar: ai mund të dërgojë mail dhe të lexojë kutinë postare për këdo që hap devtools. Thirreni nga një server, nga një funksion serverless ose nga një skript.
Kutitë e përkohshme janë përjashtimi. createTempMail() ndërton një klient që nuk mban asnjë çelës API, pra është i sigurt në një faqe. Ai krijon kuti në mënyrë anonime, dhe çdo lexim dërgon token-in që ktheu create, ose për çdo thirrje si inboxToken, ose një herë si 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 })Aty ku jepni gjithsesi dangerouslyAllowBrowser: true, API-ja lejon në preflight-in e saj CORS saktësisht Content-Type, Authorization dhe Idempotency-Key, pra një header shtesë te headers e dështon preflight-in dhe jo kërkesën, dhe ajo që raporton një shfletues për këtë nuk thotë asgjë të dobishme.