SDK

Yapılandırma

İstemci oluşturmanın üç yolu, tüm seçenekler ve bir istek gönderilmeden önce nelerin reddedildiği.

Seçenekler

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

Giriş noktası	Size ne verir
`init(options)`	Paylaşılan istemciyi yapılandırır ve döndürür. `openemail` o andan itibaren her modülde bu istemcidir ve belirtmediğiniz her şey ortamdan okunur.
`openemail`	Paylaşılan istemci. `init` çağrılmadan kullanılırsa ilk çağrıda kendini `OPENEMAIL_API_KEY` ve `OPENEMAIL_BASE_URL` üzerinden kurar.
`createOpenEmail(options)`	Aynı ortam yedeğine sahip ayrı bir istemci; paylaşılan anahtarın yanında ikinci bir anahtar için veya kendi modülünüzün dışa aktardığı örneği oluşturmak için. `createClient`, envless SDK'sının kullandığı ad altındaki aynı fonksiyondur.
`new OpenEmail(options)` veya `new OpenEmail(apiKey)`	Tam olarak verdiğiniz değerlerden kurulan ayrı bir istemci. Ortamı okumaz, bu yüzden `apiKey` zorunludur. Aynı zamanda varsayılan dışa aktarımdır.

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

Seçenek	Varsayılan	Notlar
`apiKey`	`OPENEMAIL_API_KEY`	`init` ve `createOpenEmail` tarafından ortamdan okunur. `oe_live_` veya `oe_test_` ile başlamalıdır.
`baseUrl`	`https://api.openemail.uk`	Ya da `OPENEMAIL_BASE_URL`. Sondaki eğik çizgi kırpılır; `init` ve `createOpenEmail`, çıplak bir konak adının önüne `https://`, localhost'un önüne ise `http://` ekler.
`timeoutMs`	30000	Çağrı başına değil, deneme başınadır. Yalnızca başlıkları değil, gövdenin okunmasını da kapsar. 0 devre dışı bırakır.
`maxRetries`	2	İlkinden sonraki ek denemeler; yalnızca yinelenmesi güvenli çağrılarda. Çağrı başına değil, istemci üzerinde ayarlanır.
`fetch`	global olan	Sizin için bağlanır. Bir proxy, bir Worker bağlaması veya bir test sahtesi için kendiniz geçirin.
`headers`	`{}`	Her istekte gönderilir.
`userAgent`	`openemail-sdk/<version>`	Ayarlanmasına izin vermeyen tarayıcı dışında her çalışma zamanından gönderilir.
`disableUpdateNotice`	false	npm üzerinde daha yeni bir sürüm olup olmadığına dair süreç başına bir kez yapılan denetimi atlar. Denetim yalnızca çıktı bir terminale gittiğinde çalışır ve `OPENEMAIL_DISABLE_UPDATE_NOTICE` da onu kapatır.
`dangerouslyAllowBrowser`	false	İstemcinin `window` ve `document` bulunan bir ortamda başlamasına izin verir. Bir sayfa için değil, bunları tanımlayan bir test düzeneği için düşünülmüştür.

Göndermeden önce neleri reddeder

Bunlar, ilk gönderiminizde kafa karıştırıcı bir hata olarak ortaya çıkmak yerine, yanlış değeri taşıyan satırdan düz bir Error fırlatır. Mesaj, neyin yanlış olduğunu ve yerine ne geçirilmesi gerektiğini söyler.

Reddedilen	Neden
Hiç anahtar yok	Ne `apiKey` ne de `OPENEMAIL_API_KEY` ayarlanmış; dolayısıyla kimlik doğrulaması yapacak bir şey yok.
Bir oturum çerezi veya oturum token'ı	Burada yalnızca `oe_live_` ve `oe_test_` kimlik doğrular ve API da aynı şeyi söyler. Denetim yalnızca bir ön ek denetimidir, fazlası değil; bu yüzden iptal edilmiş bir anahtar yine de ağ üzerinde başarısız olur.
http veya https URL'si olmayan bir `baseUrl`	Başka hiçbir şey getirilemez ve doğrulanmamış bir değer daha sonra bambaşka bir yerden ham bir `TypeError` olarak patlardı.
Tarayıcı	Anahtar, geliştirici araçlarını açan herkes tarafından okunabilir olurdu. Aşağıdaki bölüme bakın.
Hiçbir yerde `fetch` yok	`fetch` olarak bir tane geçirin veya Node 20+ üzerinde çalıştırın.
Herhangi bir metotta boş veya tamamı noktadan oluşan bir id	Metot çağrıldığında fırlatılır. Noktalardan oluşan bir yol parçası her URL ayrıştırıcısı tarafından kaldırılır; dolayısıyla istek başka bir uç noktaya ulaşırdı.

testMode diye bir seçenek yok ve olmayacak. Anahtar şeması bir ipucu değil, kimlik bilgisinin parçasıdır; dolayısıyla mod anahtarın bir özelliğidir. openemail.mode ön eki okur ve hiçbir karar vermez.

Tek istemci, birkaç anahtar

İstemciyi bir kez oluşturup paylaşın. İstek başına yeni bir örnek, fetch bağlamasını ve yapılandırmayı boşuna çöpe atar ve üzerindeki durumların hiçbiri çağıran başına değildir.

Birkaç çalışma alanı adına gönderim yapan bir iş gibi, aksi hâlde anahtar başına bir örnek gerektirecek durumlarda apiKey değerini çağrıda geçirin. O istek için Authorization başlığının yerini alır ve istemcide arkasında hiçbir iz bırakmaz.

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

tempMail dışındaki her metot bunu son argümanında, signal ile birlikte alır; bir liste çağrısında ise bu nesne filtrelerle aynı nesnedir. İstek gönderilmeden önce, yapıcının kullandığı kuralla denetlenir; böylece bir yazım hatası, sonradan aramak zorunda kalacağınız bir kimlik bilgisi hakkında 401 yerine { apiKey } on this call diyen bir Error fırlatır. Yeniden denenen bir çağrı kendisine verilen anahtarı korur.

signal bir AbortSignal'dır. İptal etmek isteği ve arkasında bekleyen her yeniden denemeyi durdurur.

openemail.mode, istemcinin KURULDUĞU anahtarı tanımlar ve bir geçersiz kılmayı izlemez. Tek bir istemci birkaç anahtara hizmet ettiğinde bildirilecek tek bir mod kalmaz; bu yüzden modu geçirdiğiniz anahtardan okuyun.

Tarayıcıdan

İstemci bir tarayıcıda başlamayı reddeder ve herhangi bir istek çıkmadan önce hata fırlatır. Sayfadaki bir anahtar, yayımlamış olduğunuz bir anahtardır: geliştirici araçlarını açan herkes için posta gönderebilir ve posta kutusunu okuyabilir. Bunun yerine bir sunucudan, bir sunucusuz fonksiyondan veya bir betikten çağırın.

Tek kullanımlık gelen kutuları istisnadır. createTempMail(), hiç API anahtarı taşımayan bir istemci kurar; bu yüzden bir sayfada güvenlidir. Gelen kutularını anonim olarak oluşturur ve her okuma, create çağrısının döndürdüğü token'ı gönderir: ya çağrı başına inboxToken olarak ya da bir kez createTempMail({ inboxToken }) şeklinde.

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

Yine de dangerouslyAllowBrowser: true geçirdiğinizde, API'nin CORS ön denetiminden tam olarak Content-Type, Authorization ve Idempotency-Key geçer; dolayısıyla headers içindeki fazladan bir başlık isteği değil ön denetimi başarısız kılar ve tarayıcının bunun için bildirdiği şey işe yarar hiçbir şey söylemez.