SDK
Megnyitás- és kattintáskövetés
Az `emails.getTracking` és a teljes `tracking` erőforrás.
Egy üzenet
const report = await openemail.emails.getTracking('msg_…') console.log(report.openCount, 'opens from', report.recipients.length, 'recipients')for (const link of report.links) console.log(link.url, link.clickCount)Az az üzenet, amelyet soha nem követtünk, OpenEmailApiError kivételt dob, amelynek az isNotFound értéke igaz – nem üres jelentést. A „semmit nem rögzítettünk” és a „senki nem nyitotta meg” két különböző válasz, és nem oszthatnak egy válaszon.
A postafiók egészén
await openemail.tracking.list({ opened: false, days: 7, limit: 100 })await openemail.tracking.getStats({ days: 30, offsetMinutes: -new Date().getTimezoneOffset() })await openemail.tracking.get('msg_…')await openemail.tracking.listOpens('msg_…', { includeMachine: true })await openemail.tracking.listClicks('msg_…')A list, a listOpens és a listClicks sima tömbbel tér vissza. A get, a listOpens és a listClicks elfogadja a msg_… küldésazonosítót és a követési rekord saját tmsg_… azonosítóját is.
Saját erőforrás, nem az emails mezői, és ennek az oka a lefedettség: az emails küldési rekordokat sorol fel, amelyek csak azokhoz a levelekhez léteznek, amelyeket ez az API kezelt. A szerkesztő, az MCP-eszközök és az asszisztens mind küld ilyen nélkül, így az emails alapján épített jelentés az API-forgalmadról szólna, nem a postafiókról.
A számok becsületes olvasása
| Mezőpár | Mit jelent |
|---|---|
| `opens` / `clicks` | Amit ALKALMAZTUNK: pixellel, illetve átírt linkekkel ment-e ki az üzenet. |
| `opened` / `clicked` | Ami történt. |
| `openCount` | Beszámított találatok. A szkennerek és az adatvédelmi proxyk kizárva. |
| `openCountRaw` | Minden találat. Ezt idézni elköteleződésként így lesz a megnyitási arány 100% fölötti. |
| `attributable` | Egyáltalán hozzáköthető-e az olvasás egy megnevezett címzetthez. |
A tracking.getStats arányai a KÖVETETT üzenetekre vonatkoznak, soha nem minden elküldöttre. Különben az a postafiók, amely tíz üzenetből egyet követ, úgy nézne ki, mintha összeomlott volna.
Paraméterek: tracking.list
openedboolean- A `true` azokat az üzeneteket választja ki, amelyeken legalább egy beszámított megnyitás van, a `false` azokat a követett üzeneteket, amelyeken egy sincs. Egyik sem alapértelmezés, és a `false` soha nem jelent nem követett levelet, amely ebben a listában meg sem jelenik.
clickedboolean- Ugyanez a szűrő a beszámított kattintásokra, az `opened` mezőtől függetlenül alkalmazva. Mindkettő megadható, és az üzeneteknek mindkettőnek meg kell felelniük.
daysnumber- Hány napra visszamenőleg nézzünk a mostani időponttól, 1 és 365 között, alapértelmezés szerint 30; ezen a tartományon kívül 422. Az ablakot a követési rekord létrejöttének ideje alapján mérjük, és csak azokat a rekordokat soroljuk fel, amelyek küldése ténylegesen el is ment.
limitnumber- Legfeljebb ennyi üzenet, 1 és 200 között, alapértelmezés szerint 50, a legújabbtól kezdve. Nincs kurzor: ez egy ablakra vonatkozó jelentés, nem folyam, így a `days` és a `limit` határolja, és egészben olvasandó.
Válasz: TrackingResource
object'tracking'- Mindig `'tracking'` azon a jelentésen, amelyet önmagáért kértünk le a `tracking.get`, a `tracking.list` vagy az `emails.getTracking` hívással. Ugyanez a jelentés `email.tracking` néven beágyazva egy lekért üzenetbe már e kulcs nélkül érkezik, mert ott annak az objektumnak a része, nem önálló lekérés eredménye.
idstring- A követési rekord saját azonosítója, `tmsg_…`. A találatonkénti `listOpens` és `listClicks` hívások erre kulcsolódnak; a nekik átadott `msg_…` azonosítót előbb erre oldjuk fel.
sendIdstring | null- A `msg_…` küldés, amelyhez ez korrelál, és null ott, ahol nem íródott küldési rekord. A szerkesztő, az MCP `sendEmail` eszköze és az asszisztens mind küld ilyen nélkül. A követés a postafiókot fedi le, nem csak az API-forgalmat.
threadIdstring | null- A továbbítás után töltjük ki, hogy egy olvasói felület újra megtalálja az üzenetet, és null ott, ahol a meghajtó nem jelentett egyet sem. Nem tartószerkezet: az a rekord, amelyen ez null, ugyanúgy számít.
messageIdstring | null- Az RFC 5322 Message-ID, nem a mi azonosítónk. Szintén a továbbítás után töltjük ki, és null ott, ahol a szállítás nem adott vissza semmit hozzá.
subjectstring | null- A tárgy a küldéskori állapot szerint. Null azon az üzeneten, amelyet tárgy nélkül rögzítettünk.
fromstring- A küldő cím, a rekordra másolva, nem a küldésből összekapcsolva. A jelentéseket jóval később olvassák, és az azóta javított vagy eltávolított cím egyébként átírná a történelmet.
sourceEmailSource | (string & {})- Melyik felület küldte: `composer`, `api`, `mcp`, `ai` vagy `queue`. Nyitott típus, hogy egy olyan felület, amelyet ez az SDK még nem nevez meg, ne jelentsen törő változást.
sentAtstring | null- Mikor ment el az üzenet, ISO-8601 időpontként. Null azon a rekordon, amelynek a küldése soha nem fejeződött be. A `tracking.list` ezeket kihagyja, a `get` nem.
opensboolean- ALKALMAZTUNK-e pixelt erre az üzenetre. Ez az, amit tettünk, nem az, amit a fiók beállítása most mond.
clicksboolean- Átírtuk-e ennek az üzenetnek a linkjeit. Hamis, ha a törzsben nem volt link, mert akkor semmi nem változott, és az ezt állító rekordot nem lehetne összeegyeztetni a bájtokkal.
openedboolean- Rögzítettünk-e bármilyen beszámított megnyitást a példányok között. Az `opens` mezővel együtt olvasd: az, hogy nincs adat, mert nem gyűjtöttünk, más tény, mint az, hogy senki nem olvasta el az üzenetet.
clickedboolean- Rögzítettünk-e bármilyen beszámított kattintást. Erősebb bizonyíték, mint a megnyitás, mivel a képeket sokkal gyakrabban blokkolják, mint amilyen gyakran a linkeket nem követik.
attributableboolean- Minden itteni olvasás hozzáköthető-e megnevezett címzetthez. Abban a pillanatban hamis, amint egy hozzá nem köthető példányon beszámított aktivitás jelenik meg – ez a többcímzettes eset, amikor egy törzs megy az egész listának egyetlen token alatt –, ezért ellenőrizd, mielőtt leírnád, hogy „Bob nem nyitotta meg ezt”.
openCountnumber- Azok a megnyitások, amelyeket vélhetően ember okozott, a példányokra összegezve. A gépi találatokat kizárjuk, a harminc másodpercen belüli ismétléseket pedig egybeolvasztjuk, így ez az a szám, amelyet az olvasó elé lehet tenni.
clickCountnumber- A beszámított kattintások, a példányokra összegezve. Linkenként deduplikálva, nem üzenetenként, így két különböző link másodpercek különbséggel való követése két kattintás.
openCountRawnumber- Minden pixellekérés, a szkennereket és az adatvédelmi proxykat is beleértve. Az `openCountRaw - openCount` mutatja, hányat tett félre az osztályozó, és ez az egyetlen elérhető bizonyíték arra, hogy a szűrés egyáltalán megtörtént.
clickCountRawnumber- Minden látogatás egy átírt linken, a gépi találatokat és az ismétléseket is beleértve.
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.
lastOpenAtstring | null- A legutóbbi beszámított megnyitás a példányok között, null, amíg nincs ilyen.
firstClickAtstring | null- A legkorábbi beszámított kattintás a példányok között, null, amíg nincs ilyen.
lastClickAtstring | null- A legutóbbi beszámított kattintás a példányok között, null, amíg nincs ilyen.
recipientsTrackingRecipientResource[]- Követett példányonként egy bejegyzés: címzettenként ott, ahol a szállítás engedi, hogy a bájtok személyenként eltérjenek, és egyetlen közös bejegyzés ott, ahol nem. A közös bejegyzést elhagyjuk, hacsak ténylegesen nem landolt rajta valami, így egy érintetlen „valaki” sor soha nem áll valódi nevek mellett.
recipients[].emailstring | null- Kinek ment ez a példány, kisbetűsítve és a küldéskori állapot szerint. Pontosan akkor null, amikor az `attributed` hamis.
recipients[].kind'to' | 'cc' | 'bcc' | null- Melyik fejlécen szerepelt a cím, hogy a jelentés úgy olvasódjon, ahogy az üzenet. Null a közös példányon, amely egyetlen címhez sem tartozik.
recipients[].attributedboolean- Megnevez-e ez a sor egy személyt. Az `email` mező előtt ezt olvasd: a hamis a közös példány, amelyet felsorolunk, amint bármilyen találat landol rajta, és ha nevet adnánk ennek a találatnak – akár egyetlen címzettes üzeneten is –, épp azt az egy tényt találnánk ki, amelyet a mechanizmus nem tud megadni.
recipients[].openCountnumber- Beszámított megnyitások kizárólag ezen a példányon, ugyanazokkal a kizárásokkal, mint az üzenet összesített értéke: a gépi találatokat elhagyjuk, a harminc másodpercen belüli ismétléseket pedig egybeolvasztjuk.
recipients[].clickCountnumber- Beszámított kattintások kizárólag ezen a példányon, linkenként deduplikálva, nem példányonként.
recipients[].firstOpenAtstring | null- A legkorábbi beszámított megnyitás ezen a példányon, null, amíg nincs ilyen.
recipients[].lastOpenAtstring | null- A legutóbbi beszámított megnyitás ezen a példányon, null, amíg nincs ilyen.
recipients[].firstClickAtstring | null- A legkorábbi beszámított kattintás ezen a példányon, null, amíg nincs ilyen.
recipients[].lastClickAtstring | null- A legutóbbi beszámított kattintás ezen a példányon, null, amíg nincs ilyen.
linksTrackingLinkResource[]- Minden link, amelyet ebben az üzenetben átírtunk, a törzsbeli helyük szerint rendezve. Üres ott, ahol egy sem volt: `clicks` nélkül küldött üzenetnél, vagy olyannál, amelynek a törzsében egyáltalán nem volt link.
links[].idstring- A link saját azonosítója, `lnk_…`. Ezt az értéket nevezi meg egy kattintási sor `linkId` mezője, így a `listClicks` hívásból érkező találat visszapárosítható az itteni bejegyzéssel.
links[].urlstring- Hová vezet ténylegesen a link, úgy, ahogy az üzenetben szerepelt az átírás előtt. Az átirányító az azonosítót erre oldja vissza, és továbbküldi a látogatót.
links[].labelstring | null- A horgonyszöveg úgy, ahogy az üzenetben megjelent, vagy null ott, ahol a linknek nem volt ilyenje, például képnél vagy csupasz URL-nél. Azért van, hogy a jelentés azt írhassa, „az árazási link”, ahelyett hogy egy három követési paraméterrel megtűzdelt URL-t idézne, és soha nem helyettesíti az `url` mezőt.
links[].clickCountnumber- Beszámított látogatások ezen a linken, a példányokra összegezve. Ugyanaz a linkenkénti harminc másodperces ablak, mint az üzenet `clickCount` értékénél.
links[].clickCountRawnumber- Minden látogatás ezen a linken, a gépi találatokat és az ismétléseket is beleértve.