SDK

Listeleme ve getirme

`emails.list`, `emails.listAll`, `emails.iterate`, `emails.get` ve `emails.listEvents`.

emails.list

list-emails.ts

const first = await openemail.emails.list({  status: ['queued', 'scheduled'],  from: '[email protected]',  limit: 50,}) const second = first.nextCursor  ? await openemail.emails.list({ status: ['queued', 'scheduled'], limit: 50, cursor: first.nextCursor })  : null

Bir sayfa { items, hasMore, nextCursor } biçimindedir. Sonraki sayfa için nextCursor değerini aynı filtrelerle cursor olarak geri geçirin.

emails.iterate ve emails.listAll

iterate-emails.ts

for await (const email of openemail.emails.iterate({ status: 'failed' })) {  console.error(email.id, email.lastError)} const failures = await openemail.emails.listAll({ status: 'failed', from: '[email protected]' })

İkisi de nextCursor değerini sizin için izler. iterate bir sayfayı yalnızca döngü oraya ulaştığında getirir, dolayısıyla döngüden çıkmak istekleri durdurur; listAll ise tek bir diziye çözülmeden önce her sayfayı dolaşır, bu yüzden ona sonu olan bir filtre verin. Her iki durumda da keyset sayfalama kullanılır; böylece gezinme sırasında gelen bir mesaj, offset'in yapacağı gibi bir satırı atlamanıza yol açamaz.

emails.get ve emails.listEvents

get-email.ts

const email = await openemail.emails.get('msg_…')console.log(email.status, email.recipients) const events = await openemail.emails.listEvents('msg_…')for (const event of events) console.log(event.type, event.createdAt)

recipients alanını döndüren tek çağrı get'tir; adres başına bir satır. Her biri alıcılarını taşıyan elli mesajlık bir liste, kimsenin istemediği bir rapor sayfası olurdu.

Parametreler

statusEmailStatus | EmailStatus[]: Bir veya birkaç durum (`queued`, `scheduled`, `sending`, `sent`, `partial`, `cancelled`, `failed`); verilenlerden herhangi biriyle eşleşir. SDK bir diziyi virgülle ayrılmış tek bir değer olarak gönderir, çünkü sunucu virgüllerden böler; bu kümenin dışındaki bir değer, bilinmeyeni adıyla belirten bir 422 verir.
fromstring: Kaydedildiği hâliyle gönderen adresle birebir eşleşme; yani küçük harfe çevrilmiş çıplak `addr@host`. Satır, görünen ad temizlenerek yazılır; dolayısıyla `Acme <[email protected]>` gibi açılı ayraçlı bir adres hiçbir şeyle eşleşmez. Verdiğiniz değer karşılaştırmadan önce küçük harfe çevrilir ve bu bir önek veya alan adı eşleşmesi değil, eşitlik karşılaştırmasıdır.
limitnumber: Bu sayfadaki satır sayısı, 1 ila 100, varsayılan 25. Bu aralığın dışındaki bir değer sınıra çekilmek yerine 422 ile reddedilir.
cursorstring: Sayfalamanın başlayacağı mesaj id'si (`msg_…`). Offset değil keyset: satırlar o mesajın `createdAt` değerinden kesinlikle daha eski olarak gelir; böylece sayfa dolaşılırken gelen gönderimler bir satırı sizden öteye itemez. Bu çalışma alanında hiçbir mesajı göstermeyen bir id 400 verir.

Yanıt: Page<EmailResource>

itemsEmailResource[]: `createdAt` değerine göre en yeniden eskiye sıralanmış tek sayfalık mesaj; API'nin `data` zarfından çıkarılmıştır. Liste satırları adres başına `recipients` dökümünü asla taşımaz. O döküm `get` üzerindedir.
hasMoreboolean: Filtreyle eşleşen, bu sayfanın ötesinde başka satır olup olmadığı. İkinci bir sayım sorgusuyla değil, `limit` değerinden bir satır fazla getirilerek yanıtlanır.
nextCursorstring | null: `cursor` olarak geri geçirilecek id; son sayfada null olur. `iterate` ve `listAll`, bu değer null olduğunda veya `hasMore` false olduğunda durur; çünkü daha fazlası olduğunu söyleyip cursor vermeyen bir sayfa sonsuza dek döngüye girerdi.
items[].object'email': Bu listenin satırlarında her zaman `'email'`.
items[].idstring: Bu API'nin kendi id'si, `msg_…`. Diğer tüm emails uç noktalarının aldığı ve bir cursor'ın gösterdiği değer budur.
items[].statusEmailStatus: Mesajın yaşam döngüsünde nerede olduğu. `partial`, başarısızlığın bir türü değil kendi başına bir durumdur: bazı alıcılar mesajı almıştır ve bu geri alınamaz, dolayısıyla yeniden denemek yanlıştır.
items[].modeApiKeyMode: `live` veya `test`; gönderen anahtardan alınır. Test gönderimi burada kaydedilir ve asla iletilmez.
items[].fromstring: Gönderimin yetkilendirildiği adres; çıplak ve küçük harfli olarak saklanır, dolayısıyla `from` alanında verilen bir görünen ad ağ üzerinde yine de gider ama burada tutulmaz. Nesne değil düz dizgedir, çünkü bu, yetkilendirilmiş kimliktir: bir anahtarın gönderim kapsamı dışındaki, ne sahip olduğu bir alan adında bulunan ne de üzerinde adı geçen bir adres, sahip olduğu bir adresle sessizce değiştirilmez, 403 ile reddedilir.
items[].subjectstring | null: Saklandığı hâliyle konu. Konusuz kaydedilmiş bir mesajda null.
items[].messageIdstring | null: RFC 5322 Message-ID; bizim id'miz değil. MIME oluşana kadar null'dır ve gönderim servisi tarafından çıkışta yeniden yazılır; dolayısıyla sonraki bir geri dönüş veya DSN farklı bir id taşır ve bunun yerine `items[].id` üzerinden eşleştirilir.
items[].threadIdstring | null: Bu mesajın ait olduğu konuşma dizisi; bir dizi verilmiş veya atanmışsa. Aksi hâlde null.
items[].transportEmailTransport | (string & {}) | null: Baytların nasıl gittiği. Gönderime kadar null'dır ve tipi açık bırakılmıştır; böylece bu SDK'nın henüz adlandırmadığı bir taşıma katmanı kırıcı bir değişiklik olmaz: saklanan kayıtlar artık kullanılmayan katmanları da adlandırabilir.
items[].attemptsnumber: Mesaj için kaç gönderim denemesi yapıldığı; ilkinden önce 0.
items[].lastErrorstring | null: En son gönderim hatası, bir insan için yazılmış. Hiçbir şey başarısız olmadıkça null.
items[].scheduledAtstring | null: Mesajın ne zaman gitmesi gerektiği, bir ISO-8601 anı olarak. Yalnızca iptal penceresi olmayan anlık bir gönderimde null olur: pencere kısa bir gecikmeden ibarettir, bu yüzden `cancellableForSeconds` de burayı doldurur; üstelik `status` değeri `scheduled` değil `queued` olan bir satırda.
items[].cancellableUntilstring | null: Mesajın gitmesi gereken an; ertelenmiş her gönderimde `scheduledAt` ile aynı değeri, ertelenmemiş bir gönderimde ise null taşır. Sunucunun yaptığı sınama değil, gösterilecek bir zaman damgasıdır: `cancel`, `status` üzerinden dallanır ve bir mesajı yalnızca hâlâ `queued` veya `scheduled` iken durdurur.
items[].sentAtstring | null: Ne zaman gittiği. Gönderim tamamlanana kadar null'dır; dallanılacak alanın bu değil `status` olmasının nedeni de budur.
items[].tagsRecord<string, string>: Gönderimde verilen etiketler; aynen geri döndürülür ve asla yorumlanmaz. Her zaman bir nesnedir (hiçbiri ayarlanmamışsa `{}`, asla null değil) ve yalnızca yansıtılır: bu uç nokta `status` ve `from` üzerinden filtreler, dolayısıyla bir etiket mesaj bulmanın yolu değil, bir mesajdan okunacak bir şeydir.
items[].sourceEmailSource: Gönderimi hangi yüzeyin istediği: `composer`, `api`, `mcp`, `ai` veya `queue`. `api` bu istemcidir.
items[].createdAtstring: Gönderim kaydının ne zaman yazıldığı; bu, gönderimden öncedir. Listenin sıraladığı ve bir cursor'ın karşılaştırdığı alan budur.
items[].trackingEmailTrackingSummary: Etkileşim özeti; yalnızca mesajı izlenmiş bir satırda bulunur, aksi hâlde hiç bulunmaz. “Bu izlendi mi?” sorusunun yanıtı yokluğudur; `openCount: 0` ise “kimse açmadı” diye okunurdu.
items[].tracking.opensboolean: Bu mesajın bir pikselle gidip gitmediği. Hesap ayarının şu anda ne dediği değil, bu mesaja ne uygulandığı.
items[].tracking.clicksboolean: Bu mesajın bağlantılarının yeniden yazılıp yazılmadığı. Gövdede yeniden yazılacak bağlantı yoksa false olur, çünkü o zaman hiçbir şey değiştirilmemiştir.
items[].tracking.openedboolean: Sayılan herhangi bir açılma kaydedilip kaydedilmediği; `openCount > 0` ifadesinden türetilir.
items[].tracking.clickedboolean: Sayılan herhangi bir tıklama kaydedilip kaydedilmediği; `clickCount > 0` ifadesinden türetilir.
items[].tracking.openCountnumber: Bir insanın yol açtığına inanılan açılmalar, mesajın her kopyası üzerinden toplanır. Tarayıcı botları ve gizlilik vekilleri kaydedilir ama hariç tutulur; otuz saniye içindeki tekrarlı istekler tek bir açılmaya indirgenir.
items[].tracking.clickCountnumber: Sayılan tıklamalar, kopyalar üzerinden toplanır. Mesaj başına değil bağlantı başına tekilleştirilir, çünkü saniyeler arayla iki bağlantıya tıklamak bir tekrar değil iki ayrı eylemdir.
items[].tracking.firstOpenAtstring | null: Kopyalar arasındaki en erken sayılan açılma; hiç yoksa null. Makine istekleri bunu asla değiştirmez.
items[].translationEmailTranslationResource: Bir liste satırında asla bulunmaz: çeviri kaydı, listenin bilerek getirmediği saklanan istekte yer alır. Buradaki yokluğu, mesajın çevrilip çevrilmediği hakkında hiçbir şey söylemez. `get` çağrısına sorun.