Megnyitás- és kattintáskövetés

Két független kapcsoló, mindkettő bekapcsolva, hacsak ki nem kapcsolták annál a címnél, amelyről az üzenet megy, vagy az Összes címnél. Az opens egy 1×1-es képet fűz hozzá; a clicks átírja a törzs új részében lévő linkeket. A válasz alatti idézett előzmény valaki más üzenete, azt békén hagyjuk. A küldés a tracking: { opens, clicks } mezővel dönt egyetlen üzenetről (mindkét irányban, tehát a false az, ahogyan egy program elhárítja, amit a cím beállítása előírna), a kihagyott mező pedig annak a címnek a beállítására esik vissza, amelyről küldik, majd az Összes címre, nem pedig egy olyan alapértékre, amelyet ez az API választott a munkaterület nevében.

{    "from": "Acme Billing <[email protected]>",    "to": ["[email protected]"],    "subject": "Your September invoice",    "html": "<p>Invoice attached.</p>",    "tracking": { "opens": true, "clicks": true }  }

Üzenetenként legfeljebb 100 célt írunk át, mindegyiket egyszer. A fejléc képéből, egy gombból és a láblécből hivatkozott ugyanazon URL egyetlen sor, mert egyetlen kérdés, háromszor feltéve. A korlát fölött a maradék linkek pontosan úgy maradnak, ahogy megírták őket: a nem követett link is működik, és az az üzenet, amely csendben elveszíti az utolsó kétszáz linkjét, sokkal rosszabb hiba, mint egy hiányos jelentés.

Az átírt linkek és a pixel alapértelmezetten az OpenEmail API hostjára mutatnak. Ha a küldő domainnek van egyéni követési domainje, amelynek tracking.status értéke active, a domainről induló új levél helyette a https://<követési host>/t/... címet használja, és a PATCH /domains/{id} az, ahol beállíthatsz egyet.

Ez azért önálló erőforrás, nem néhány mező az /emails végponton, a lefedettség miatt: az a lista küldési rekordokat tart, a szerkesztő, az MCP eszközök és az asszisztens viszont mind úgy küldenek, hogy nem írnak ilyet. Az arra épülő jelentés az API forgalmadról szólna, nem a postafiókról.

{    "object": "tracking",    "id": "tmsg_9c1f7b2e4a5d40b8a3e61d2f",    "sendId": "msg_c5f21cc6bfec4e848caf905b",    "threadId": "thread_2f9b…",    "messageId": "<2598…@acme.com>",    "subject": "Your September invoice",    "from": "[email protected]",    "source": "api",    "sentAt": "2026-08-29T08:19:08.000Z",    "opens": true,    "clicks": true,    "opened": true,    "clicked": true,    "attributable": true,    "openCount": 3,    "openCountRaw": 7,    "clickCount": 1,    "clickCountRaw": 2,    "firstOpenAt": "2026-08-29T09:04:11.000Z",    "lastOpenAt": "2026-08-30T07:42:55.000Z",    "firstClickAt": "2026-08-29T09:05:02.000Z",    "lastClickAt": "2026-08-29T09:05:02.000Z",    "recipients": [      {        "email": "[email protected]",        "kind": "to",        "attributed": true,        "openCount": 3,        "clickCount": 1,        "firstOpenAt": "2026-08-29T09:04:11.000Z",        "lastOpenAt": "2026-08-30T07:42:55.000Z",        "firstClickAt": "2026-08-29T09:05:02.000Z",        "lastClickAt": "2026-08-29T09:05:02.000Z"      }    ],    "links": [      {        "id": "lnk_4f0a1c8d29b74e6fa3c05d17",        "url": "https://acme.com/invoices/42",        "label": "View invoice",        "clickCount": 1,        "clickCountRaw": 2      }    ]  }

Az opens és a clicks az, amit az üzenetre ALKALMAZTUNK; az opened és a clicked az, ami történt. Az openCount az olvasásokat számolja, az openCountRaw a lekéréseket. A különbség, itt négy, a szkennerek és az adatvédelmi proxyk, és azért tartjuk meg, hogy a napló és az összeg közötti rés megvizsgálható legyen, ne megmagyarázatlan. Az attributable az a mező, amelyet el kell olvasni, mielőtt bárkit megneveznél: a hamis azt jelenti, hogy az olvasás egy olyan példányon történt, amely az egész listának ment ki, és onnantól minden egy adott címzettről szóló mondat találgatás.

A source azt a felületet nevezi meg, amely küldte: api az ezen az API-n át küldött üzenetnél, composer mindennél, amit maga az alkalmazás küldött. A sendId a második fajtánál null, és ezért létezik a követési azonosító.

{    "object": "tracking_stats",    "tracked": 128,    "trackedForOpens": 128,    "trackedForClicks": 47,    "opened": 91,    "clicked": 34,    "openRate": 71.1,    "clickRate": 72.3,    "totalOpens": 240,    "totalClicks": 52,    "machineOpens": 173,    "medianTimeToOpenSeconds": 2714,    "byDay": [{ "day": "2026-08-27", "sent": 12, "opened": 9, "clicked": 3 }],    "topLinks": [{ "url": "https://acme.com/pricing", "label": "See pricing", "clickCount": 18 }],    "clients": [{ "client": "Gmail", "count": 96 }],    "countries": [{ "country": "GB", "count": 71 }]  }

Az arányok a KÖVETETT üzenetekre vett százalékok, nem az összes elküldött levélre: annak a munkaterületnek, amely tíz üzenetből egyet követ, azokra a tízre van megnyitási aránya, és ha mindennel osztanánk, amit valaha küldött, az arány minden nem követett válasz után esne. Az ötször megnyitott üzenet EGY megnyitott üzenet. Az arányok üzeneteket számolnak, az összegek találatokat, és a kettő összemosásából születnek a 100% fölötti megnyitási arányok.

{    "object": "list",    "data": [      {        "object": "open",        "id": "opn_1a7c…",        "trackedMessageId": "tmsg_9c1f7b2e4a5d40b8a3e61d2f",        "recipient": "[email protected]",        "kind": "machine",        "counted": false,        "client": "Apple Mail Privacy Protection",        "device": "unknown",        "os": "macOS",        "country": "GB",        "region": "England",        "city": "London",        "createdAt": "2026-08-29T08:19:11.000Z"      }    ]  }

A kind értéke human, proxy vagy machine, a counted pedig megmondja, mozdította-e a számokat. A gépi találatokat kizárjuk, hacsak nem adod át az includeMachine=true paramétert, és ez a becsületes alapértelmezés: azért rögzítjük őket, mert az elhagyásuk megmagyarázhatatlan rést hagyna, nem mert érdeklődést jelentenének.

• —Az Apple Mail Privacy Protection kézbesítéskor minden üzenet minden képét lekéri, akár megnézi valaki, akár nem. A User-Agent és a hálózat alapján osztályozzuk, és machine értékként rögzítjük, ahogy mindent, ami a küldéstől számított tíz másodpercen belül érkezik, mert amit ember csinál, az nem történik ilyen gyorsan.
• —A Gmail képproxyja proxy, nem machine: valaki megjelenítette az üzenetet, tehát a megnyitás valódi, miközben az eszköz, a kliens és a hely nem megismerhető. A proxy ráadásul gyorsítótáraz, így egy második olvasás lehet, hogy el sem jut hozzánk. A Gmailen át mért számok alsó korlátok, soha nem összegek.
• —Ugyanannak a példánynak harminc másodpercen belüli két lekérése egy olvasás. Az újrarajzoló előnézeti ablak vagy a visszagördített üzenet újra lekéri a képet; az egy órával későbbi valódi második látogatást viszont továbbra is számoljuk.
• —A címzett megnevezéséhez olyan üzenet kell, amely elég kicsi ahhoz, hogy személyenként újraépítsük: a becsült méret szorozva a címzettek számával 8MB alatt kell maradjon. Efölött egy törzs megy mindenkinek, és minden rajta lévő találat hozzárendelés nélküli.
• —Az az üzenet, amelyen kattintás van, megnyitás nincs, biztosan olvasott: a képeket sokkal gyakrabban blokkolják, mint ahányszor egy linkre nem kattintanak. A két számlálót külön olvasd, ne add össze őket.
• —Ha link nélküli törzsre kérsz kattintáskövetést, semmit nem rögzítünk: a kimenő bájtok azonosak egy nem követett küldéssel, és az ezzel ellentétes sort semmivel nem lehetne összeegyeztetni. Ugyanez igaz arra az üzenetre, amelynek nincs átírható törzse.
• —Az OpenEmail kiszedi az 1×1-es képeket abból a levélből, amelyet a saját felhasználói olvasnak, az általa küldött pixellel együtt, és maga rögzíti a megnyitást, amikor az üzenetet megjelenített képekkel nyitják meg. Az a találat human, az OpenEmail klienssel. Elrejtett képekkel semmit nem rögzítünk.

A számolt megnyitás email.opened, a számolt kattintás email.clicked eseményt vált ki minden feliratkozott végponton, és mindkettő bekerül az üzenet saját eseménynyomvonalába, ha az ezen az API-n ment át. Egyik sem sül el szkennernél vagy adatvédelmi proxynál. Azok kitolása pontosan azzal a forgalommal töltené meg a fogadó naplóját, amelyet az osztályozó a számokon kívül igyekszik tartani.

A letöltési linkként kiment fájl ugyanígy jelent. A számolt letöltés email.downloaded eseményt vált ki, ugyanarra a nyomvonalra kerül, és ugyanaz az osztályozó tartja ki belőle a szkennereket és a linkelőnézőket, így a szám embereket jelent. A hasznos teher megnevezi a fájlt (shareId, fileId, filename, mimeType, sizeBytes, url) a downloadCount, a first és a downloadedAt mezőkkel, azok mellett a kliens- és helymezők mellett, amelyeket egy kattintás is visz. A recipient mindig null, az attributed mindig hamis: a letöltési link egyetlen URL az üzenet minden címzettjének, így egy letöltést nem lehet egyikükhöz kötni.

const report = await openemail.tracking.get('msg_c5f21cc6bfec…')const cold = await openemail.tracking.list({ days: 30, opened: false })const stats = await openemail.tracking.getStats({  days: 30,  offsetMinutes: -new Date().getTimezoneOffset(),})

Itt minden hívás egyszerű olvasás, és a kliens mindegyiket külön próbálja újra. A get OpenEmailApiError hibát dob, amelynek isNotFound mezője igaz arra az üzenetre, amelyet soha nem követtünk, és ez az a megkülönböztetés, amelyet érdemes megőrizni abban, amibe betáplálod.