SDK

Beszélgetések

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

Olvasás

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)

Az API pageToken értékkel lapozza a beszélgetéseket. A kliens nextCursor néven adja át neked, és cursor néven veszi vissza, mint minden más listánál, a listAll és az iterate pedig helyetted követi. Átlátszatlan: azt add vissza, amit kaptál, és soha ne építs ilyet.

Rendszerezés

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

Az olvasottsági állapot itt minden backenden címke, ezért a címkelistákkal együtt utazik, és a sorrend determinisztikus, ha mindkettőt beállítod. A három mező közül legalább egynek jelen kell lennie.

Egy üzenet mellékletei

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

A content base64, és üres string, ha a tárolt bájtok nem találhatók, ezért dekódolás előtt nézd meg a hosszát. A titkosított üzenet titkosított szövege BENNE VAN ebben a listában, és ugyanúgy letölthető, mint bármely más fájl; a PGP/MIME verzió-rész és az esetleges különálló aláírás nincs. Ezek az azonosítójukat az encryption.parts mezőben őrzik, és semmi többet.

Titkosítottan érkezett üzenet

Ez az SDK sem titkosít, sem visszafejt: nem tud megnyitni olyan üzenetet, amelyet valaki más titkosított, és titkosítottat sem tud küldeni. A küldési kérés elutasításra kerül, ha titkosítási jelölőt hordoz, mert a kulcs nélküli kliensnek semmi keresnivalója nincs egy ilyen állításnál. Az OpenEmail alkalmazásban generált kulcsok abban a böngészőben élnek, amely létrehozta őket, és ide semmi nem jut el belőlük; amikor az a böngésző megnyit egy lezárt üzenetet, a nyílt szöveg benne marad, és a tárolt üzenet, amelyet ez a hívás olvas, továbbra is titkosított szöveg. Amit a threads.get ad, az a felismert boríték. A PGP- vagy S/MIME-burkolatban érkezett üzenet encryption objektumot hordoz, így az üres decodedBody már nem az egyetlen, amit kapsz, és az encryption az egyetlen mező a MessageResource típuson, amelynek valódi típusa van, mert ennek a hiányát nem lehet túlélni találgatással.

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

Az isSealed alapján ágazz el, soha ne a mező meglétére. Az öt formátum közül kettő, a pgp-signed és az smime-signed, olyan törzset ír le, amely NYÍLTAN érkezett egy különálló aláírás mellett, így a meglétre kapuzás olyan levelet rejt el, amelyet senkinek nem kellett elrejtenie, a felhasználó pedig nem látja és nem tudja megmagyarázni. Az isSealed pontosan ezért része a csomagnak: a szerver egyszer kimondja a lezárt halmazt, és az unióból kiírt harmadik másolat az, amelyik elsodródik.

A hiány nem jelent nyílt szöveget. Az encryption hiányzik minden olyan üzenetről, amelyet a felismerés bevezetése előtt tároltak, és mindenről, ami olyan úton jutott a postafiókba, ahol a felismerő soha nem futott. Azt rögzíti, hogy senki nem nézte meg – ez a lefedettségünkről szóló tény, nem a levélről –, és semmi nem tölti fel utólag.

Miben térnek el ezek a többitől

A ThreadResource.messages minden eleme egy MessageResource: egy Record<string, unknown>, pontosan egy megnevezett mezővel. A többi típusozása azt jelentené, hogy a kliens olyan normalizálást állít, amelyet senki nem végez el, az encryption viszont mégis meg van nevezve, mert az a kliens, amely nem tud rá elágazni, a lezárt üzenetet üresnek olvassa.
Az a kérés, amelyet nem lehet hűen kiszolgálni, 422 capability_unsupported hibát kap, nem pedig olyan választ, amely helyesnek látszik, és csendben téves.

Paraméterek: threads.list (ThreadListOptions)

folderstring: Melyik mappát listázza. A szerver alapértéke az `inbox`, így az elhagyása szűkíti a listát, nem pedig mindenre tágítja. A `query` keresésre is vonatkozik, hacsak a lekérdezés maga nem nevez meg mappát `in:` operátorral vagy olyan mappát jelölő `is:` operátorral, mint az `is:sent`.
querystring: A postafiók keresési szintaxisa. Az egyszerű szavaknak mind szerepelniük kell, és mindegyik lazán illeszkedik: a kis- és nagybetű, az ékezetek és az elválasztók nem számítanak, és egy hosszabb szó része is találat, így a `min` és a `ben jamin` is megtalálja a „Benjamin” szót. Az idézőjeles kifejezés a kis- és nagybetűtől, valamint az ékezetektől eltekintve szó szerint illeszkedik, így a `"ben jamin"` nem találja meg a „Ben-Jamin” alakot, a töltelékszavak pedig kiesnek, ha marad más, amire keresni lehet. Szűkíts olyan operátorokkal, mint a `from:ada`, a `label:Invoices`, az `is:unread`, a `has:pdf`, a `before:2026/01/31` és az `older_than:1y`, és kombináld őket `OR` kulcsszóval, zárójelekkel és egy vezető `-` jellel; azt az értéket, amelyet a keresés nem tud használni, figyelmen kívül hagyja, nem szűkít vele. A szavak, valamint a `from:`, `to:`, `cc:`, `subject:` és `body:` operátorok a legutóbbi üzenet feladóját, címzettjeit, tárgyát és a törzse első 4000 karakterét olvassák jelölés nélkül, míg a `filename:` és a `has:` a teljes beszélgetés minden mellékletét olvassa, a címkék és a mappák pedig a teljes beszélgetést. Ugyanazt az indexet szűkíti, amelyet a szűretlen listázás olvas. A lezárt üzenetek nem tárolnak törzsszöveget, ezért csak a feladójuk, a címzettjeik és a tárgyuk illeszkedhet.
labelIdsstring | string[]: Szűkíti a listát azokra a beszélgetésekre, amelyek ezeket a címkéket viselik. A végpont vesszővel elválasztott stringet vár, a kliens pedig helyetted fűzi össze a tömböt eggyé; nincs korlát, hányat nevezel meg.
limitnumber: Hány beszélgetést adjon vissza, 1-től 100-ig. Ha elhagyod, a kezelő 25-öt használ. Az alapérték a kezelőben él, nem a sémában, így a hiányzó érték és a kifejezetten megadott 25 egyformán viselkedik.
cursorstring: Az előző oldal `nextCursor` értéke, szó szerint visszaadva. Ez az API `pageToken` mezője azon a néven, amelyet minden más lista használ, és átlátszatlan, ezért soha ne állíts elő vagy szerkessz ilyet.

Válasz: Page<ThreadSummaryResource>

itemsThreadSummaryResource[]: Beszélgetésenként egy bejegyzés ezen az oldalon, az API `data` borítékjából kiemelve. Minden bejegyzés csupán egy objektumjelölő és egy azonosító. A lista nem hordoz tárgyat, részletet, résztvevőket vagy címkéket, tehát bármi többhöz a kívánt beszélgetéseken meg kell hívni a `threads.get` metódust.
items[].idstring: A beszélgetés azonosítója, amelyet változatlanul kell átadni a `threads.get`, a `threads.update` és a többi hívásnak. Ugyanaz az azonosító, akár szűrt listából, akár `query` keresésből származik a sor.
hasMoreboolean: Van-e további oldal; a `nextCursor` értékéből származtatva ott, ahol az API nem mondja ki.
nextCursorstring | null: Az API `nextPageToken` értéke, amelyet a következő oldalhoz `cursor` néven kell visszaküldeni, vagy null, ha nincs további oldal. Az üres token nullra normalizálódik, így a falsy vizsgálat és a null vizsgálat egyetért.