SDK
Seguiment d'obertures i clics
`emails.getTracking` i tot el recurs `tracking`.
Un sol missatge
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)Un missatge del qual mai no s'ha fet seguiment llança un OpenEmailApiError amb isNotFound cert, no pas un informe buit. «No hem registrat res» i «ningú no l'ha obert» són respostes diferents i no han de compartir una mateixa resposta.
A tota la bústia
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 i listClicks es resolen en arrays plans. get, listOpens i listClicks accepten tant l'id d'enviament msg_… com el tmsg_… propi del registre de seguiment.
És un recurs propi i no pas camps dins d'emails, i el motiu és la cobertura: emails llista registres d'enviament, que només existeixen per al correu que ha gestionat aquesta API. El redactor, les eines d'MCP i l'assistent envien sense cap registre, de manera que un informe construït sobre emails seria un informe sobre el teu trànsit d'API i no pas sobre la bústia.
Llegir les xifres amb honestedat
| Parell | Què significa |
|---|---|
| `opens` / `clicks` | Què es va APLICAR: si el missatge va sortir amb un píxel o amb els enllaços reescrits. |
| `opened` / `clicked` | Què va passar. |
| `openCount` | Impactes comptabilitzats. S'exclouen els escàners i els proxies de privadesa. |
| `openCountRaw` | Tots els impactes. Citar això com a interacció és la manera que una taxa d'obertura superi el 100%. |
| `attributable` | Si una lectura es pot atribuir o no a un destinatari concret. |
Les taxes de tracking.getStats es calculen sobre els missatges RASTREJATS, mai sobre tot el que s'ha enviat. Altrament, una bústia que rastreja un missatge de cada deu semblaria que s'ha enfonsat.
Paràmetres: tracking.list
openedboolean- `true` selecciona els missatges amb almenys una obertura comptabilitzada; `false` selecciona els missatges rastrejats que no en tenen cap. Cap dels dos és el valor per defecte, i `false` mai no vol dir correu no rastrejat, que no apareix gens en aquesta llista.
clickedboolean- El mateix filtre per als clics comptabilitzats, aplicat independentment d'`opened`. Es poden indicar tots dos, i els missatges han de complir-los tots dos.
daysnumber- Quants dies enrere cal mirar des d'ara, d'1 a 365 i amb 30 per defecte; fora d'aquest interval és un 422. La finestra es mesura sobre el moment en què es va crear el registre de seguiment, i només es llisten els registres l'enviament dels quals va sortir realment.
limitnumber- Com a màxim aquest nombre de missatges, d'1 a 200 i amb 50 per defecte, els més recents primer. No hi ha cursor: això és un informe sobre una finestra i no pas un flux, de manera que està limitat per `days` i `limit` i es llegeix sencer.
Resposta: TrackingResource
object'tracking'- Sempre `'tracking'` en un informe obtingut per si mateix, mitjançant `tracking.get`, `tracking.list` o `emails.getTracking`. El mateix informe imbricat com a `email.tracking` en un missatge recuperat arriba sense aquesta clau, perquè allà forma part d'aquell objecte en lloc de ser una cosa que s'hagi obtingut.
idstring- L'id propi del registre de seguiment, `tmsg_…`. És la clau de les crides per impacte `listOpens` i `listClicks`; un `msg_…` que se'ls passi es resol abans cap a aquest.
sendIdstring | null- L'enviament `msg_…` amb què es correlaciona, i null quan no s'ha escrit cap registre d'enviament. El redactor, el `sendEmail` d'MCP i l'assistent envien tots sense cap. El seguiment cobreix la bústia, no només el trànsit de l'API.
threadIdstring | null- S'omple després de la transmissió perquè una interfície de lectura pugui tornar a trobar el missatge, i és null quan el controlador no n'ha informat de cap. No és determinant: un registre amb aquest camp a null continua comptant.
messageIdstring | null- El Message-ID de RFC 5322, no el nostre id. També s'omple després de la transmissió, i és null quan el transport no ha retornat res per omplir-lo.
subjectstring | null- L'assumpte tal com era en el moment de l'enviament. Null en un missatge registrat sense cap.
fromstring- L'adreça remitent, copiada al registre en lloc d'unir-s'hi des de l'enviament. Els informes es llegeixen molt després dels fets, i una adreça corregida o eliminada d'aleshores ençà reescriuria la història.
sourceEmailSource | (string & {})- Quina superfície el va enviar: `composer`, `api`, `mcp`, `ai` o `queue`. Té un tipus obert perquè una superfície que aquest SDK encara no anomena no sigui un canvi incompatible.
sentAtstring | null- Quan va sortir el missatge, com a instant ISO-8601. Null en un registre l'enviament del qual no es va completar mai. `tracking.list` els exclou; `get` no.
opensboolean- Si es va APLICAR un píxel a aquest missatge. Això és el que es va fer, no el que diu ara la configuració del compte.
clicksboolean- Si els enllaços d'aquest missatge es van reescriure. Fals quan el cos no contenia cap enllaç, perquè llavors no es va canviar res i un registre que afirmés el contrari no es podria conciliar amb els bytes.
openedboolean- Si s'ha registrat alguna obertura comptabilitzada entre les còpies. Llegeix-ho en contrast amb `opens`: no tenir dades perquè no se'n van recollir és un fet diferent que ningú no hagi llegit el missatge.
clickedboolean- Si s'ha registrat algun clic comptabilitzat. És una evidència més sòlida que una obertura, ja que les imatges es bloquegen molt més sovint que no pas es deixen de seguir els enllaços.
attributableboolean- Si cada lectura d'aquí es pot atribuir a un destinatari concret. Fals en el moment que una còpia sense atribuir mostra activitat comptabilitzada, que és el cas de diversos destinataris en què un sol cos va a tota la llista amb un únic token; comprova-ho abans d'escriure «en Bob no ho ha obert».
openCountnumber- Obertures que es creu que ha provocat una persona, sumades sobre les còpies. S'exclouen els impactes automàtics i les repeticions en menys de trenta segons es fusionen en una de sola, de manera que aquesta és la xifra que cal posar davant d'un lector.
clickCountnumber- Clics comptabilitzats, sumats sobre les còpies. Es desdupliquen per enllaç i no per missatge, de manera que dos enllaços diferents seguits amb segons de diferència són dos clics.
openCountRawnumber- Totes les peticions del píxel, incloent-hi escàners i proxies de privadesa. `openCountRaw - openCount` és quantes n'ha apartat el classificador, i l'única evidència disponible que el filtratge s'ha arribat a fer.
clickCountRawnumber- Totes les visites a un enllaç reescrit, incloent-hi impactes automàtics i repeticions.
firstOpenAtstring | null- L'obertura comptabilitzada més antiga entre les còpies, i null mentre no n'hi hagi cap. Els impactes automàtics no la mouen mai.
lastOpenAtstring | null- L'obertura comptabilitzada més recent entre les còpies, null mentre no n'hi hagi cap.
firstClickAtstring | null- El clic comptabilitzat més antic entre les còpies, null mentre no n'hi hagi cap.
lastClickAtstring | null- El clic comptabilitzat més recent entre les còpies, null mentre no n'hi hagi cap.
recipientsTrackingRecipientResource[]- Una entrada per còpia rastrejada: una per destinatari quan el transport permet que els bytes difereixin per persona, i una única entrada compartida quan no ho permet. L'entrada compartida es descarta tret que hi hagi caigut alguna cosa de debò, de manera que una fila «algú» intacta no seu mai al costat de noms reals.
recipients[].emailstring | null- A qui va anar aquesta còpia, en minúscules i tal com era en el moment de l'enviament. Null exactament quan `attributed` és fals.
recipients[].kind'to' | 'cc' | 'bcc' | null- En quina capçalera apareixia l'adreça, perquè un informe es llegeixi tal com es llegia el missatge. Null a la còpia compartida, que no pertany a cap adreça.
recipients[].attributedboolean- Si aquesta fila anomena una persona. Llegeix-ho abans que `email`: fals és la còpia compartida, que es llista tan bon punt hi cau qualsevol impacte, i posar un nom a aquest impacte, fins i tot en un missatge amb un únic destinatari, seria inventar l'únic fet que el mecanisme no pot aportar.
recipients[].openCountnumber- Obertures comptabilitzades només en aquesta còpia, amb les mateixes exclusions que el total del missatge: els impactes automàtics es descarten i les repeticions en menys de trenta segons es fusionen en una de sola.
recipients[].clickCountnumber- Clics comptabilitzats només en aquesta còpia, desduplicats per enllaç i no per còpia.
recipients[].firstOpenAtstring | null- L'obertura comptabilitzada més antiga en aquesta còpia, null mentre no n'hi hagi cap.
recipients[].lastOpenAtstring | null- L'obertura comptabilitzada més recent en aquesta còpia, null mentre no n'hi hagi cap.
recipients[].firstClickAtstring | null- El clic comptabilitzat més antic en aquesta còpia, null mentre no n'hi hagi cap.
recipients[].lastClickAtstring | null- El clic comptabilitzat més recent en aquesta còpia, null mentre no n'hi hagi cap.
linksTrackingLinkResource[]- Tots els enllaços que es van reescriure en aquest missatge, ordenats segons on eren al cos. Buit quan no n'hi va haver cap: un missatge enviat amb `clicks` desactivat, o un el cos del qual no contenia cap enllaç.
links[].idstring- L'id propi de l'enllaç, `lnk_…`. És el valor que anomena el `linkId` d'una fila de clic, de manera que un impacte de `listClicks` es pot fer correspondre amb l'entrada d'aquí.
links[].urlstring- On va realment l'enllaç, tal com era al missatge abans de la reescriptura. El redirector resol un id fins a aquest valor i hi envia el visitant.
links[].labelstring | null- El text de l'àncora tal com apareixia al missatge, o null quan l'enllaç no en tenia, com ara una imatge o una URL nua. Hi és perquè un informe pugui dir «l'enllaç de preus» en lloc de citar una URL amb tres paràmetres de seguiment, i mai no substitueix `url`.
links[].clickCountnumber- Visites comptabilitzades a aquest enllaç, sumades sobre les còpies. La mateixa finestra de trenta segons per enllaç que `clickCount` al missatge.
links[].clickCountRawnumber- Totes les visites a aquest enllaç, incloent-hi impactes automàtics i repeticions.