SDK
Sledování otevření a kliknutí
`emails.getTracking` a celý zdroj `tracking`.
Jedna zpráva
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)Zpráva, která nikdy nebyla sledována, vyhodí OpenEmailApiError, jehož isNotFound je true, ne prázdné hlášení. „Nic jsme nezaznamenali“ a „nikdo to neotevřel“ jsou různé odpovědi a nesmí sdílet jednu odpověď.
Napříč schránkou
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_…')list, listOpens a listClicks se vyhodnocují na prostá pole. get, listOpens a listClicks přijímají buď id odeslání msg_…, nebo vlastní tmsg_… záznamu o sledování.
Samostatný zdroj místo polí na emails, a důvodem je pokrytí: emails vypisuje záznamy o odeslání, které existují jen pro poštu, kterou obsloužilo toto API. Editor zpráv, nástroje MCP i asistent odesílají bez něj, takže hlášení postavené na emails by bylo hlášením o vašem provozu přes API, ne o schránce.
Jak čísla číst poctivě
| Dvojice | Co to znamená |
|---|---|
| `opens` / `clicks` | Co bylo UPLATNĚNO: zda zpráva odešla s pixelem nebo s přepsanými odkazy. |
| `opened` / `clicked` | Co se stalo. |
| `openCount` | Započítané přístupy. Skenery a soukromí chránící proxy se nezapočítávají. |
| `openCountRaw` | Všechny přístupy. Uvádět tohle jako míru interakce je způsob, jak míra otevření přesáhne 100 %. |
| `attributable` | Zda je vůbec možné přečtení přiřadit konkrétnímu jmenovanému příjemci. |
Míry z tracking.getStats se počítají ze SLEDOVANÝCH zpráv, nikdy ze všeho odeslaného. Jinak by schránka, která sleduje jednu zprávu z deseti, vypadala, jako by se zhroutila.
Parametry: tracking.list
openedboolean- `true` vybere zprávy s alespoň jedním započítaným otevřením, `false` vybere sledované zprávy bez jediného. Ani jedna hodnota není výchozí a `false` nikdy neznamená nesledovanou poštu, která se v tomto seznamu vůbec neobjevuje.
clickedboolean- Týž filtr pro započítaná kliknutí, uplatněný nezávisle na `opened`. Lze zadat oba a zprávy musí vyhovovat oběma.
daysnumber- Kolik dní zpět od teď se má hledat, 1 až 365, výchozí 30; mimo tento rozsah jde o 422. Okno se měří podle toho, kdy byl záznam o sledování vytvořen, a vypisují se jen záznamy, jejichž odeslání skutečně proběhlo.
limitnumber- Nejvýše tolik zpráv, 1 až 200, výchozí 50, od nejnovějších. Kurzor neexistuje: jde o hlášení za určité okno, ne o proud, takže je ohraničené hodnotami `days` a `limit` a čte se celé najednou.
Odpověď: TrackingResource
object'tracking'- Vždy `'tracking'` u hlášení načteného samostatně, přes `tracking.get`, `tracking.list` nebo `emails.getTracking`. Totéž hlášení vnořené jako `email.tracking` u načtené zprávy tento klíč nemá, protože tam je součástí onoho objektu, ne něčím, co bylo načteno zvlášť.
idstring- Vlastní id záznamu o sledování, `tmsg_…`. Je to klíč, na kterém stojí volání po jednotlivých přístupech `listOpens` a `listClicks`; `msg_…` jim předané se nejprve převede na tohle.
sendIdstring | null- Odeslání `msg_…`, ke kterému se tento záznam vztahuje; null tam, kde žádný záznam o odeslání zapsán nebyl. Editor zpráv, `sendEmail` v MCP i asistent odesílají bez něj. Sledování pokrývá celou schránku, ne jen provoz přes API.
threadIdstring | null- Vyplňuje se po přenosu, aby čtecí rozhraní dokázalo zprávu znovu najít; null tam, kde ovladač žádnou hodnotu nenahlásil. Není nosné: záznam, kde je null, se počítá stejně.
messageIdstring | null- Message-ID podle RFC 5322, ne naše id. Také se vyplňuje po přenosu a je null tam, kde transport nevrátil nic, čím by se vyplnilo.
subjectstring | null- Předmět ve tvaru platném v době odeslání. Null u zprávy zaznamenané bez předmětu.
fromstring- Odesílací adresa, zkopírovaná do záznamu, ne připojená joinem z odeslání. Hlášení se čtou dlouho po události a adresa, která byla mezitím opravena nebo odstraněna, by jinak přepsala historii.
sourceEmailSource | (string & {})- Které rozhraní zprávu odeslalo: `composer`, `api`, `mcp`, `ai` nebo `queue`. Typ je otevřený, aby rozhraní, které toto SDK ještě nepojmenovává, nebylo rozbíjející změnou.
sentAtstring | null- Kdy zpráva odešla, jako okamžik podle ISO-8601. Null u záznamu, jehož odeslání nikdy nedoběhlo. `tracking.list` takové vynechává, `get` ne.
opensboolean- Zda byl na tuto zprávu UPLATNĚN pixel. Jde o to, co se stalo, ne o to, co říká nastavení účtu teď.
clicksboolean- Zda byly odkazy v této zprávě přepsány. False, když tělo žádné odkazy nemělo, protože pak se nic nezměnilo a záznam tvrdící opak by nešel srovnat se skutečnými bajty.
openedboolean- Zda bylo napříč kopiemi zaznamenáno nějaké započítané otevření. Čtěte to spolu s `opens`: žádná data proto, že se žádná nesbírala, je jiná skutečnost než to, že zprávu nikdo nečetl.
clickedboolean- Zda bylo zaznamenáno nějaké započítané kliknutí. Je to silnější důkaz než otevření, protože obrázky bývají blokovány mnohem častěji, než zůstávají odkazy neotevřené.
attributableboolean- Zda lze každé zde uvedené přečtení přiřadit jmenovanému příjemci. False v okamžiku, kdy nepřiřazená kopie vykáže započítanou aktivitu, což je případ více příjemců, kdy jedno tělo jde celému seznamu pod jediným tokenem – zkontrolujte to tedy dřív, než napíšete „Bob tohle neotevřel“.
openCountnumber- Otevření, o kterých se předpokládá, že je způsobil člověk, sečtená přes kopie. Strojové přístupy se nezapočítávají a opakování do třiceti sekund se slučují do jednoho, takže tohle je číslo, které se dává před čtenáře.
clickCountnumber- Započítaná kliknutí, sečtená přes kopie. Deduplikují se po jednotlivých odkazech, ne po zprávě, takže dva různé odkazy otevřené pár sekund po sobě jsou dvě kliknutí.
openCountRawnumber- Každé načtení pixelu, včetně skenerů a soukromí chránících proxy. `openCountRaw - openCount` říká, kolik jich klasifikátor odložil stranou, a je to jediný dostupný důkaz, že k filtrování vůbec došlo.
clickCountRawnumber- Každá návštěva přepsaného odkazu, včetně strojových přístupů a opakování.
firstOpenAtstring | null- Nejstarší započítané otevření napříč kopiemi; dokud žádné není, null. Strojové přístupy jím nikdy nepohnou.
lastOpenAtstring | null- Nejnovější započítané otevření napříč kopiemi; dokud žádné není, null.
firstClickAtstring | null- Nejstarší započítané kliknutí napříč kopiemi; dokud žádné není, null.
lastClickAtstring | null- Nejnovější započítané kliknutí napříč kopiemi; dokud žádné není, null.
recipientsTrackingRecipientResource[]- Jedna položka na každou sledovanou kopii: na příjemce tam, kde transport dovolí, aby se bajty pro každého lišily, a jediná sdílená položka tam, kde to nedovolí. Sdílená položka se zahodí, pokud na ni skutečně něco nedopadlo, takže nedotčený řádek „někdo“ nikdy nestojí vedle skutečných jmen.
recipients[].emailstring | null- Komu tato kopie šla, malými písmeny a ve tvaru platném v době odeslání. Null přesně tehdy, když je `attributed` false.
recipients[].kind'to' | 'cc' | 'bcc' | null- V které hlavičce se adresa objevila, aby se hlášení četlo stejně jako zpráva. Null u sdílené kopie, která nepatří žádné konkrétní adrese.
recipients[].attributedboolean- Zda tento řádek pojmenovává konkrétního člověka. Čtěte jej dřív než `email`: false je sdílená kopie, která se vypíše, jakmile na ni dopadne jakýkoli přístup, a přiřadit tomuto přístupu jméno – i u zprávy s jediným příjemcem – by znamenalo vymyslet si přesně tu jedinou skutečnost, kterou mechanismus poskytnout neumí.
recipients[].openCountnumber- Započítaná otevření jen na této kopii, za stejných vyloučení jako u součtu za zprávu: strojové přístupy se zahazují a opakování do třiceti sekund se slučují do jednoho.
recipients[].clickCountnumber- Započítaná kliknutí jen na této kopii, deduplikovaná po jednotlivých odkazech, ne po kopii.
recipients[].firstOpenAtstring | null- Nejstarší započítané otevření na této kopii; dokud žádné není, null.
recipients[].lastOpenAtstring | null- Nejnovější započítané otevření na této kopii; dokud žádné není, null.
recipients[].firstClickAtstring | null- Nejstarší započítané kliknutí na této kopii; dokud žádné není, null.
recipients[].lastClickAtstring | null- Nejnovější započítané kliknutí na této kopii; dokud žádné není, null.
linksTrackingLinkResource[]- Každý odkaz, který byl v této zprávě přepsán, seřazený podle toho, kde v těle stál. Prázdné tam, kde žádný nebyl: u zprávy odeslané s vypnutým `clicks` nebo u zprávy, jejíž tělo neobsahovalo vůbec žádný odkaz.
links[].idstring- Vlastní id odkazu, `lnk_…`. Je to hodnota, kterou uvádí `linkId` u řádku kliknutí, takže přístup z `listClicks` lze spárovat zpět s položkou zde.
links[].urlstring- Kam odkaz skutečně vede, ve tvaru, v jakém byl ve zprávě před přepsáním. Přesměrovač id převede zpět na tuhle hodnotu a návštěvníka pošle dál.
links[].labelstring | null- Text odkazu tak, jak se objevil ve zprávě, nebo null tam, kde odkaz žádný neměl, například u obrázku nebo holé URL. Je tam proto, aby hlášení mohlo říct „odkaz na ceník“ místo citování URL se třemi sledovacími parametry, a nikdy `url` nenahrazuje.
links[].clickCountnumber- Započítané návštěvy tohoto odkazu, sečtené přes kopie. Totéž třicetisekundové okno na odkaz jako u `clickCount` na zprávě.
links[].clickCountRawnumber- Každá návštěva tohoto odkazu, včetně strojových přístupů a opakování.