SDK

Listázás és lekérés

`emails.list`, `emails.listAll`, `emails.iterate`, `emails.get` és `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

Az oldal alakja { items, hasMore, nextCursor }. A nextCursor értéket add vissza cursor néven, ugyanazokkal a szűrőkkel, a következő oldalhoz.

emails.iterate és 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]' })

Mindkettő helyetted követi a nextCursor értéket. Az iterate csak akkor kér le egy oldalt, amikor a ciklus odaér, így a kilépés leállítja a kéréseket, míg a listAll minden oldalt bejár, mielőtt egyetlen tömbbel visszatérne, ezért olyan szűrőt adj neki, amely véget ér. Mindkét esetben keyset-lapozás, így egy menet közben érkező üzenet nem tud sort kihagyatni veled, ahogy az offset tenné.

emails.get és 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)

A get az egyetlen hívás, amely recipients mezőt ad vissza, címenként egy sorral. Az ötven üzenetből álló lista, amelyen mindegyik hordozza a címzettjeit, olyan jelentésoldal, amelyet senki nem kért.

Paraméterek

statusEmailStatus | EmailStatus[]: Egy vagy több állapot (`queued`, `scheduled`, `sending`, `sent`, `partial`, `cancelled`, `failed`), amelyek közül bármelyikre illeszkedik. Az SDK a tömböt egyetlen vesszővel elválasztott értékként küldi, mert a kiszolgáló vesszőnél bont; a halmazon kívüli érték 422, amely megnevezi az ismeretlent.
fromstring: Pontos egyezés a küldő címre úgy, ahogy rögzítettük, vagyis a csupasz, kisbetűs `addr@host` alakra. A sort megjelenítendő név nélkül írjuk, így egy szögletes zárójeles alak, például az `Acme <[email protected]>`, semmire nem illeszkedik. Az általad megadott értéket összehasonlítás előtt kisbetűsítjük, és egyenlőségről van szó, nem előtag- vagy domainegyezésről.
limitnumber: Sorok ezen az oldalon, 1 és 100 között, alapértelmezés szerint 25. A tartományon kívüli értéket 422-vel utasítjuk el, nem vágjuk le.
cursorstring: Egy üzenetazonosító (`msg_…`), amelytől lapozunk. Keyset, nem offset: a sorok szigorúan régebbiek annak az üzenetnek a `createdAt` értékénél, így a menet közben érkező küldések nem tolhatnak át sorokat rajtad. Az olyan azonosító, amely ezen a munkaterületen nem nevez meg üzenetet, 400.

Válasz: Page<EmailResource>

itemsEmailResource[]: Egy oldalnyi üzenet, `createdAt` szerint a legújabbtól kezdve, kiemelve az API `data` borítékából. A listasorok soha nem hordozzák a címenkénti `recipients` bontást. Az a `get` hívásnál van.
hasMoreboolean: Van-e a szűrőre illeszkedő további sor ezen az oldalon túl. Ezt úgy válaszoljuk meg, hogy a `limit` értéknél eggyel több sort kérünk le, nem pedig egy második darabszám-lekérdezéssel.
nextCursorstring | null: Az azonosító, amelyet `cursor` néven kell visszaadni, és null az utolsó oldalon. Az `iterate` és a `listAll` megáll, ha ez null, vagy ha a `hasMore` hamis, mivel az az oldal, amely továbbiakat állít, de nem nevez meg kurzort, örökké pörögne.
items[].object'email': Ennek a listának a sorain mindig `'email'`.
items[].idstring: Ennek az API-nak a saját azonosítója, `msg_…`. Ezt várja minden más emails-végpont, és ezt nevezi meg a kurzor.
items[].statusEmailStatus: Hol tart az üzenet az életútján. A `partial` önálló állapot, nem a hiba egy változata: egyes címzetteknél már ott van, és nem lehet visszaszívni, így az újraküldés hibás lépés.
items[].modeApiKeyMode: `live` vagy `test`, a küldő kulcsból véve. A tesztküldést rögzítjük, de soha nem továbbítjuk.
items[].fromstring: A cím, amellyel a küldést engedélyeztük, csupaszon és kisbetűsítve tárolva, így a `from` mezőben megadott megjelenítendő név kimegy ugyan a hálózatra, de itt nem őrizzük meg. Sima sztring, nem objektum, mert ez az az identitás, amelyet engedélyeztünk: a kulcs küldési köréből kieső címet – amely sem a birtokolt domainjén nincs, sem külön megnevezve nincs – 403-mal utasítjuk el, soha nem cseréljük csendben olyanra, amely megengedett.
items[].subjectstring | null: A tárgy úgy, ahogy tároltuk. Null azon az üzeneten, amelyet tárgy nélkül rögzítettünk.
items[].messageIdstring | null: Az RFC 5322 Message-ID, nem a mi azonosítónk. Null, amíg a MIME nem létezik, és a küldő szolgáltatás kimenet közben átírja, így egy későbbi visszapattanás vagy DSN más azonosítót hordoz, és az `items[].id` alapján korrelál.
items[].threadIdstring | null: A beszélgetés, amelyhez ez az üzenet tartozik, ha megadtak vagy hozzárendeltek egyet. Egyébként null.
items[].transportEmailTransport | (string & {}) | null: Hogyan mentek ki a bájtok. A kiküldésig null, és nyitott típusú, hogy egy olyan szállítás, amelyet ez az SDK még nem nevez meg, ne jelentsen törő változást: a tárolt rekordok olyanokat is megnevezhetnek, amelyek már nincsenek használatban.
items[].attemptsnumber: Hány kiküldési kísérlet történt az üzenettel; az első előtt 0.
items[].lastErrorstring | null: A legutóbbi kiküldési hiba, embernek írva. Null, amíg semmi nem hibázott.
items[].scheduledAtstring | null: Mikor esedékes az üzenet indulása, ISO-8601 időpontként. Csak olyan azonnali küldésen null, amelyhez nem tartozik visszavonási ablak: az ablak csupán rövid késleltetés, így a `cancellableForSeconds` is kitölti ezt, olyan soron, amelynek a `status` értéke `queued`, nem `scheduled`.
items[].cancellableUntilstring | null: Az az időpont, amikor az üzenet indulása esedékes; minden halasztott küldésen ugyanazt az értéket hordozza, mint a `scheduledAt`, és nullát azon, amelyet nem halasztottak. Ez megjelenítendő időbélyeg, nem az a vizsgálat, amelyet a kiszolgáló végez: a `cancel` a `status` mezőre ágazik, és csak addig állít meg egy üzenetet, amíg az `queued` vagy `scheduled`.
items[].sentAtstring | null: Mikor ment el. A kiküldés befejeződéséig null, és pontosan ezért a `status` az a mező, amelyre ágazni kell, nem ez.
items[].tagsRecord<string, string>: A küldéskor megadott címkék, visszatükrözve és soha nem értelmezve. Mindig objektum (`{}`, ha egyet sem adtak meg, soha nem null), és csak visszatükrözzük: ez a végpont a `status` és a `from` mezőre szűr, így a címke olyasmi, amit egy üzenetről leolvasol, nem pedig keresési eszköz.
items[].sourceEmailSource: Melyik felület kérte a küldést: `composer`, `api`, `mcp`, `ai` vagy `queue`. Az `api` ez a kliens.
items[].createdAtstring: Mikor íródott a küldési rekord, ami a kiküldés előtt van. A lista e mező szerint rendez, és a kurzor is ehhez hasonlít.
items[].trackingEmailTrackingSummary: Az elköteleződési összesítő, amely csak olyan soron van jelen, amelynek az üzenetét követtük, egyébként hiányzik. A hiánya a válasz arra, hogy „követtük-e ezt”, míg az `openCount: 0` úgy olvasódna, hogy „senki nem nyitotta meg”.
items[].tracking.opensboolean: Pixellel ment-e ki ez az üzenet. Azt mondja meg, mit alkalmaztunk erre az üzenetre, nem azt, hogy most mit mond a fiók beállítása.
items[].tracking.clicksboolean: Átírtuk-e ennek az üzenetnek a linkjeit. Hamis, ha a törzsben nem volt átírandó link, hiszen akkor semmi nem változott.
items[].tracking.openedboolean: Rögzítettünk-e bármilyen beszámított megnyitást; az `openCount > 0` értékből származik.
items[].tracking.clickedboolean: Rögzítettünk-e bármilyen beszámított kattintást; a `clickCount > 0` értékből származik.
items[].tracking.openCountnumber: Azok a megnyitások, amelyeket vélhetően ember okozott, az üzenet minden példányára összegezve. A szkennereket és az adatvédelmi proxykat rögzítjük, de kihagyjuk, a harminc másodpercen belüli ismételt lekéréseket pedig egybeolvasztjuk.
items[].tracking.clickCountnumber: A beszámított kattintások, a példányokra összegezve. Linkenként deduplikálva, nem üzenetenként, mert két link másodpercek különbséggel való megnyitása két cselekvés, nem ismétlés.
items[].tracking.firstOpenAtstring | null: A legkorábbi beszámított megnyitás a példányok között, és null, amíg nincs ilyen. A gépi találatok soha nem mozdítják el.
items[].translationEmailTranslationResource: Listasoron soha nincs jelen: a fordítási rekord a tárolt kérésben él, amelyet a lista szándékosan nem tölt be. A hiánya itt semmit nem mond arról, hogy lefordítottuk-e az üzenetet. Kérdezd meg a `get` hívással.