SDK
Open- en kliktracking
`emails.getTracking` en de hele `tracking`-resource.
Eén bericht
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)Een bericht dat nooit getrackt is gooit een OpenEmailApiError waarvan isNotFound waar is, en geen leeg rapport. "We hebben niets vastgelegd" en "niemand heeft het geopend" zijn verschillende antwoorden en mogen geen antwoord delen.
Over de hele mailbox
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 en listClicks leveren gewone arrays op. get, listOpens en listClicks accepteren zowel de msg_…-verzend-id als de eigen tmsg_… van het trackingrecord.
Een eigen resource in plaats van velden op emails, en de reden is dekking: emails somt verzendrecords op, en die bestaan alleen voor mail die deze API heeft afgehandeld. De composer, de MCP-tools en de assistent versturen allemaal zonder er een, dus een rapport gebouwd op emails zou een rapport over je API-verkeer zijn in plaats van over de mailbox.
De cijfers eerlijk lezen
| Paar | Wat het betekent |
|---|---|
| `opens` / `clicks` | Wat er is TOEGEPAST: of het bericht met een pixel of met herschreven links vertrok. |
| `opened` / `clicked` | Wat er is gebeurd. |
| `openCount` | Getelde hits. Scanners en privacyproxy's uitgesloten. |
| `openCountRaw` | Elke hit. Dit als betrokkenheid aanhalen is hoe een open rate boven de 100% uitkomt. |
| `attributable` | Of een leesactie überhaupt aan een genoemde ontvanger kan worden toegeschreven. |
Percentages uit tracking.getStats gaan over GETRACKTE berichten, nooit over alles wat verstuurd is. Anders zou een mailbox die één bericht op de tien trackt eruitzien alsof die was ingestort.
Parameters: tracking.list
openedboolean- `true` selecteert berichten met minstens één getelde opening, `false` selecteert getrackte berichten zonder. Geen van beide is een standaard, en `false` betekent nooit ongetrackte mail, die in deze lijst helemaal niet voorkomt.
clickedboolean- Hetzelfde filter voor getelde kliks, onafhankelijk van `opened` toegepast. Beide mogen gegeven worden, en berichten moeten aan beide voldoen.
daysnumber- Hoeveel dagen terug vanaf nu gekeken wordt, 1 tot 365 en standaard 30; daarbuiten is het een 422. Het venster wordt gemeten op wanneer het trackingrecord is aangemaakt, en alleen records waarvan de verzending daadwerkelijk is uitgegaan worden vermeld.
limitnumber- Hoogstens zoveel berichten, 1 tot 200 en standaard 50, nieuwste eerst. Er is geen cursor: dit is een rapport over een venster in plaats van een feed, dus het wordt begrensd door `days` en `limit` en in zijn geheel gelezen.
Antwoord: TrackingResource
object'tracking'- Altijd `'tracking'` op een rapport dat op zichzelf is opgehaald, via `tracking.get`, `tracking.list` of `emails.getTracking`. Hetzelfde rapport genest als `email.tracking` op een opgehaald bericht arriveert zonder deze sleutel, omdat het daar onderdeel van dat object is en niet iets dat is opgehaald.
idstring- De eigen id van het trackingrecord, `tmsg_…`. Daarop zijn de aanroepen per hit, `listOpens` en `listClicks`, gesleuteld; een `msg_…` die aan hen wordt meegegeven wordt eerst hiernaartoe opgelost.
sendIdstring | null- De `msg_…`-verzending waarmee dit correleert, en null waar er geen verzendrecord is geschreven. De composer, `sendEmail` van MCP en de assistent versturen allemaal zonder er een. Tracking dekt de mailbox, niet alleen API-verkeer.
threadIdstring | null- Ingevuld na verzending zodat een lees-UI het bericht kan terugvinden, en null waar de driver er geen meldde. Niet dragend: een record waar dit null is telt gewoon mee.
messageIdstring | null- De Message-ID uit RFC 5322, niet onze id. Ook na verzending ingevuld, en null waar het transport niets teruggaf om hem mee te vullen.
subjectstring | null- Het onderwerp zoals het op het moment van verzenden was. Null op een bericht dat zonder onderwerp is vastgelegd.
fromstring- Het verzendende adres, op het record gekopieerd in plaats van uit de verzending samengevoegd. Rapporten worden lang na dato gelezen, en een adres dat sindsdien gecorrigeerd of verwijderd is zou anders de geschiedenis herschrijven.
sourceEmailSource | (string & {})- Welke oppervlakte het verstuurde: `composer`, `api`, `mcp`, `ai` of `queue`. Open getypeerd zodat een oppervlakte die deze SDK nog niet noemt geen breuk is.
sentAtstring | null- Wanneer het bericht wegging, als een ISO-8601-tijdstip. Null op een record waarvan de verzending nooit voltooide. `tracking.list` sluit die uit, `get` niet.
opensboolean- Of er een pixel op dit bericht is TOEGEPAST. Dit is wat er gedaan is, niet wat de accountinstelling nu zegt.
clicksboolean- Of de links van dit bericht zijn herschreven. Onwaar wanneer de body geen links droeg, want dan is er niets gewijzigd en zou een record dat iets anders beweert niet met de bytes te rijmen zijn.
openedboolean- Of er over de kopieën heen een getelde opening is vastgelegd. Lees het samen met `opens`: geen gegevens omdat er niets verzameld is, is een ander feit dan dat niemand het bericht gelezen heeft.
clickedboolean- Of er een getelde klik is vastgelegd. Sterker bewijs dan een opening, aangezien afbeeldingen veel vaker geblokkeerd worden dan dat links niet gevolgd worden.
attributableboolean- Of elke leesactie hier aan een genoemde ontvanger kan worden toegeschreven. Onwaar zodra een niet-toegeschreven kopie getelde activiteit vertoont, en dat is het geval met meerdere ontvangers waarbij één body onder één token naar de hele lijst gaat, dus controleer dit voordat je "Bob heeft dit niet geopend" schrijft.
openCountnumber- Openingen waarvan wordt aangenomen dat een persoon ze veroorzaakte, opgeteld over de kopieën. Machinehits zijn uitgesloten en herhalingen binnen dertig seconden vallen samen tot één, dus dit is het cijfer om een lezer voor te houden.
clickCountnumber- Getelde kliks, opgeteld over de kopieën. Ontdubbeld per link in plaats van per bericht, dus twee verschillende links die met seconden ertussen gevolgd worden zijn twee kliks.
openCountRawnumber- Elke pixelophaling, scanners en privacyproxy's inbegrepen. `openCountRaw - openCount` is hoeveel de classificatie opzij heeft gezet, en het enige beschikbare bewijs dat het filteren überhaupt heeft plaatsgevonden.
clickCountRawnumber- Elk bezoek aan een herschreven link, machinehits en herhalingen inbegrepen.
firstOpenAtstring | null- De vroegste getelde opening over de kopieën, en null zolang die er niet is. Machinehits verschuiven hem nooit.
lastOpenAtstring | null- De meest recente getelde opening over de kopieën, null zolang die er niet is.
firstClickAtstring | null- De vroegste getelde klik over de kopieën, null zolang die er niet is.
lastClickAtstring | null- De meest recente getelde klik over de kopieën, null zolang die er niet is.
recipientsTrackingRecipientResource[]- Eén item per getrackte kopie: per ontvanger waar het transport de bytes per persoon laat verschillen, en één gedeeld item waar dat niet zo is. Het gedeelde item wordt weggelaten tenzij er daadwerkelijk iets op is geland, zodat een onaangeroerde "iemand"-rij nooit naast echte namen staat.
recipients[].emailstring | null- Naar wie deze kopie ging, in kleine letters en zoals het op het moment van verzenden was. Null precies wanneer `attributed` onwaar is.
recipients[].kind'to' | 'cc' | 'bcc' | null- Op welke header het adres stond, zodat een rapport leest zoals het bericht deed. Null op de gedeelde kopie, die bij geen enkel adres hoort.
recipients[].attributedboolean- Of deze rij een persoon noemt. Lees het vóór `email`: onwaar is de gedeelde kopie, die vermeld wordt zodra er een hit op landt, en er een naam aan koppelen, zelfs bij een bericht met één ontvanger, zou precies het ene feit verzinnen dat het mechanisme niet kan leveren.
recipients[].openCountnumber- Getelde openingen op alleen deze kopie, onder dezelfde uitsluitingen als het berichttotaal: machinehits weggelaten, en herhalingen binnen dertig seconden samengevoegd tot één.
recipients[].clickCountnumber- Getelde kliks op alleen deze kopie, ontdubbeld per link in plaats van per kopie.
recipients[].firstOpenAtstring | null- De vroegste getelde opening op deze kopie, null zolang die er niet is.
recipients[].lastOpenAtstring | null- De meest recente getelde opening op deze kopie, null zolang die er niet is.
recipients[].firstClickAtstring | null- De vroegste getelde klik op deze kopie, null zolang die er niet is.
recipients[].lastClickAtstring | null- De meest recente getelde klik op deze kopie, null zolang die er niet is.
linksTrackingLinkResource[]- Elke link die in dit bericht is herschreven, geordend naar waar hij in de body stond. Leeg waar er geen waren: een bericht dat met `clicks` uit is verstuurd, of een waarvan de body helemaal geen link droeg.
links[].idstring- De eigen id van de link, `lnk_…`. Het is de waarde die de `linkId` van een klikrij noemt, zodat een hit uit `listClicks` teruggekoppeld kan worden aan het item hier.
links[].urlstring- Waar de link daadwerkelijk heen gaat, zoals hij vóór het herschrijven in het bericht stond. De redirector lost een id hiernaartoe op en stuurt de bezoeker door.
links[].labelstring | null- De ankertekst zoals die in het bericht stond, of null waar de link er geen had, zoals bij een afbeelding of een kale URL. Hij staat er zodat een rapport "de prijzenlink" kan zeggen in plaats van een URL met drie trackingparameters te citeren, en hij vervangt `url` nooit.
links[].clickCountnumber- Getelde bezoeken aan deze link, opgeteld over de kopieën. Hetzelfde venster van dertig seconden per link als `clickCount` op het bericht.
links[].clickCountRawnumber- Elk bezoek aan deze link, machinehits en herhalingen inbegrepen.