SDK

İleti dizileri

`threads.list`, `listAll`, `iterate`, `get`, `update`, `trash`, `snooze`, `unsnooze` ve `listAttachments`.

Okuma

read-threads.ts

const page = await openemail.threads.list({  folder: 'inbox',  query: 'from:ada',  labelIds: ['INBOX', 'IMPORTANT'],  limit: 25,}) const next = page.nextCursor  ? await openemail.threads.list({ folder: 'inbox', cursor: page.nextCursor })  : null const thread = await openemail.threads.get('thread_…')console.log(thread.messageCount, thread.hasUnread, thread.totalReplies)

API, ileti dizilerini bir pageToken ile sayfalar. İstemci bunu size nextCursor olarak verir ve diğer tüm listelerde olduğu gibi cursor olarak geri alır; listAll ve iterate ise onu sizin yerinize takip eder. Değer opaktır: size verileni geri gönderin ve asla kendiniz bir tane oluşturmayın.

Düzenleme

organise-threads.ts

await openemail.threads.update('thread_…', {  read: true,  addLabelIds: ['Done'],  removeLabelIds: ['INBOX'],}) await openemail.threads.trash('thread_…')await openemail.threads.snooze('thread_…', new Date(Date.now() + 86_400_000))await openemail.threads.unsnooze('thread_…')

Okundu durumu buradaki her arka uçta bir ETİKETTİR; bu yüzden etiket listeleriyle birlikte taşınır ve ikisini birden ayarladığınızda sıralama belirlenimlidir. Üç alandan en az biri bulunmalıdır.

Bir iletideki ekler

attachments.ts

const files = await openemail.threads.listAttachments('thread_…', 'message_…') for (const file of files) {  console.log(file.filename, file.contentType, file.size)  if (file.content) await save(file.filename, Buffer.from(file.content, 'base64'))}

content base64'tür ve saklanan baytlar bulunamadığında boş bir string olur; bu yüzden çözmeden önce uzunluğunu denetleyin. Şifreli bir iletinin şifreli metni bu listede BULUNUR ve diğer dosyalar gibi indirilir; PGP/MIME sürüm parçası ile ayrık imzalar ise bulunmaz. Onların id'leri yalnızca encryption.parts içinde tutulur, başka hiçbir şey saklanmaz.

Şifreli olarak gelen bir ileti

Bu SDK ne şifreler ne de şifre çözer: başkasının şifrelediği bir iletiyi açamaz ve şifreli bir ileti gönderemez. Gönderme isteği bir şifreleme işareti taşıyorsa reddedilir; çünkü anahtarı olmayan bir istemcinin böyle bir iddiada bulunmaya hakkı yoktur. OpenEmail uygulamasında üretilen anahtarlar, onları üreten tarayıcıda yaşar ve buraya hiçbir şekilde ulaşmaz; o tarayıcı mühürlü bir iletiyi açtığında düz metin tarayıcıda kalır ve bu çağrının okuduğu saklı ileti hâlâ şifreli metindir. threads.get'in size verdiği şey, tanınmış hâliyle zarftır. PGP ya da S/MIME sarmalıyla gelen bir ileti bir encryption nesnesi taşır; böylece elinize tutuşturulan tek şey boş bir decodedBody olmaktan çıkar. encryption, MessageResource üzerinde gerçek bir türe sahip tek alandır, çünkü yokluğunu tahmine dayanarak atlatamayacağınız alan odur.

encrypted-mail.ts

import { isSealed, openemail } from '@openemail/sdk' const thread = await openemail.threads.get('thread_…') for (const message of thread.messages) {  if (!message.encryption) continue  if (!isSealed(message)) continue   console.warn('cannot read this one:', message.encryption.format)}

Alanın varlığına göre değil, isSealed ile dallanın. Beş biçimden ikisi, pgp-signed ve smime-signed, ayrık bir imzanın yanında AÇIK hâlde gelen bir gövdeyi tanımlar; bu yüzden varlığa göre kapı koymak, kimsenin gizlemesi gerekmeyen postayı gizler ve kullanıcı ne onu görebilir ne de açıklayabilir. isSealed tam da bu nedenle gönderilir: sunucu mühürlü kümeyi bir kez bildirir ve birleşimden yazılmış üçüncü bir kopya, kayan kopyadır.

Yokluk, düz metin demek değildir. encryption, algılama yayımlanmadan önce saklanan her iletide ve algılayıcının hiç çalışmadığı bir yoldan posta kutusuna ulaşan her şeyde eksiktir. Kimsenin bakmadığını kaydeder; bu, postaya değil kapsamımıza dair bir olgudur ve hiçbir şey onu geriye dönük doldurmaz.

Bunların diğerlerinden ayrıldığı nokta

ThreadResource.messages içindeki her girdi bir MessageResource'tur; üzerinde tam olarak bir adlandırılmış alan bulunan bir Record<string, unknown>. Geri kalanını türlemek, istemcinin kimsenin gerçekleştirmediği bir normalleştirmeyi iddia etmesi olurdu; encryption yine de adlandırılmıştır, çünkü onun üzerinden dallanamayan bir istemci mühürlü bir iletiyi boş bir ileti olarak okur.
Sadakatle karşılanamayan bir istek, doğru görünüp sessizce yanlış olan bir yanıt değil, 422 capability_unsupported hatasıdır.

Parametreler: threads.list (ThreadListOptions)

folderstring: Hangi klasörün listeleneceği. Sunucu bunu varsayılan olarak `inbox` alır; bu yüzden atlamak, listelemeyi her şeye genişletmek yerine daraltır. Sorgu, `in:` ile ya da `is:sent` gibi bir klasör `is:` ifadesiyle kendisi bir klasör adlandırmadığı sürece, bu parametre bir `query` aramasına da uygulanır.
querystring: Posta kutusu arama sözdizimi. Düz sözcüklerin tümü geçmelidir ve her biri gevşek eşleşir: büyük/küçük harf, aksanlar ve ayırıcılar yok sayılır, daha uzun bir sözcüğün parçası da sayılır; bu yüzden hem `min` hem de `ben jamin` “Benjamin”i bulur. Tırnak içindeki bir ifade, büyük/küçük harf ve aksanlar dışında yazıldığı gibi eşleşir; bu yüzden `"ben jamin"` “Ben-Jamin”i bulmaz ve aranacak başka bir şey kaldığında dolgu sözcükleri düşürülür. `from:ada`, `label:Invoices`, `is:unread`, `has:pdf`, `before:2026/01/31` ve `older_than:1y` gibi operatörlerle daraltın ve bunları `OR`, parantezler ve başa konan bir `-` ile birleştirin; aramanın kullanamadığı bir değer daraltma yapmak yerine yok sayılır. Sözcükler ile `from:`, `to:`, `cc:`, `subject:` ve `body:` operatörleri en son iletinin göndericisini, alıcılarını, konusunu ve gövdesinin işaretlemeden arındırılmış ilk 4.000 karakterini okur; `filename:` ve `has:` ise tüm yazışmadaki her eki okur, etiketler ve klasörler de tüm yazışmayı okur. Filtresiz listelemenin okuduğu indeksin aynısını daraltır. Mühürlü iletiler hiçbir gövde metni saklamaz; bu yüzden yalnızca göndericileri, alıcıları ve konuları eşleşebilir.
labelIdsstring | string[]: Listelemeyi bu etiketleri taşıyan ileti dizileriyle sınırlar. Uç nokta virgülle ayrılmış bir string alır ve istemci bir diziyi sizin yerinize tek bir stringe birleştirir; kaç tane adlandırabileceğinize dair bir sınır yoktur.
limitnumber: Kaç ileti dizisinin döndürüleceği, 1 ile 100 arasında. Atlandığında işleyici 25 kullanır. Varsayılan, şemada değil işleyicide yaşar; bu yüzden değerin hiç verilmemesi ile açıkça 25 verilmesi aynı davranır.
cursorstring: Bir önceki sayfanın `nextCursor` değeri, olduğu gibi geri iletilir. Diğer tüm listelerin kullandığı ad altındaki API `pageToken` değeridir ve opaktır; bu yüzden asla kendiniz bir tane oluşturmayın ya da düzenlemeyin.

Yanıt: Page<ThreadSummaryResource>

itemsThreadSummaryResource[]: Bu sayfadaki her ileti dizisi için bir girdi; API'nin `data` zarfından çıkarılmıştır. Her girdi yalnızca bir nesne işareti ve bir id'dir. Listeleme konu, özet, katılımcı ya da etiket taşımaz; bu yüzden daha fazlası için istediğiniz ileti dizilerinde `threads.get` çağırmanız gerekir.
items[].idstring: İleti dizisinin id'si; `threads.get`, `threads.update` ve diğerlerine olduğu gibi verilir. Satır ister filtrelenmiş bir listelemeden ister bir `query` aramasından gelsin, id aynıdır.
hasMoreboolean: Başka bir sayfa olup olmadığı; API bunu bildirmediğinde `nextCursor`'dan türetilir.
nextCursorstring | null: API'nin `nextPageToken` değeri; sonraki sayfa için `cursor` olarak geri gönderilir ya da başka sayfa yoksa null olur. Boş bir token null'a normalleştirilir; böylece falsy denetimi ile null denetimi aynı sonucu verir.