SDK
Atvēršanas un klikšķu izsekošana
`emails.getTracking` un viss `tracking` resurss.
Viens ziņojums
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)Ziņojums, kas nekad netika izsekots, izmet OpenEmailApiError, kuram isNotFound ir true, nevis atgriež tukšu atskaiti. „Mēs neko nereģistrējām“ un „neviens to neatvēra“ ir dažādas atbildes, un tām nedrīkst būt viena un tā pati atbilde.
Visā pastkastē
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 un listClicks atrisinās par vienkāršiem masīviem. get, listOpens un listClicks pieņem vai nu msg_… sūtījuma id, vai izsekošanas ieraksta paša tmsg_….
Atsevišķs resurss, nevis lauki uz emails, un iemesls ir aptvērums: emails uzskaita sūtījumu ierakstus, kas pastāv tikai pastam, ko apstrādāja šis API. Rakstīšanas logs, MCP rīki un asistents sūta bez tāda, tāpēc atskaite, kas būvēta uz emails, būtu atskaite par jūsu API datplūsmu, nevis par pastkasti.
Kā godīgi lasīt skaitļus
| Pāris | Ko tas nozīmē |
|---|---|
| `opens` / `clicks` | Kas tika PIEMĒROTS: vai ziņojums aizgāja ar pikseli vai pārrakstītām saitēm. |
| `opened` / `clicked` | Kas notika. |
| `openCount` | Ieskaitītie trāpījumi. Skeneri un privātuma starpnieki izslēgti. |
| `openCountRaw` | Katrs trāpījums. Ja to uzdod par iesaisti, atvēršanas rādītājs pārsniedz 100 %. |
| `attributable` | Vai lasīšanu vispār var piesaistīt konkrētam nosauktam adresātam. |
Rādītāji no tracking.getStats ir par IZSEKOTAJIEM ziņojumiem, nekad par visu nosūtīto. Citādi pastkaste, kas izseko vienu ziņojumu no desmit, izskatītos pēc sabrukuma.
Parametri: tracking.list
openedboolean- `true` atlasa ziņojumus ar vismaz vienu ieskaitītu atvēršanu, `false` atlasa izsekotos ziņojumus bez nevienas. Neviens no tiem nav noklusējums, un `false` nekad nenozīmē neizsekotu pastu, kas šajā sarakstā vispār neparādās.
clickedboolean- Tas pats filtrs ieskaitītiem klikšķiem, piemērots neatkarīgi no `opened`. Var dot abus, un ziņojumiem jāatbilst abiem.
daysnumber- Cik dienas atpakaļ no šī brīža skatīties, no 1 līdz 365, pēc noklusējuma 30; ārpus šī diapazona tas ir 422. Logs tiek mērīts pēc izsekošanas ieraksta izveides laika, un tiek uzskaitīti tikai tie ieraksti, kuru sūtījums patiešām aizgāja.
limitnumber- Ne vairāk kā tik ziņojumu, no 1 līdz 200, pēc noklusējuma 50, jaunākie vispirms. Kursora nav: šī ir atskaite par laika logu, nevis plūsma, tāpēc to ierobežo `days` un `limit` un to lasa veselu.
Atbilde: TrackingResource
object'tracking'- Vienmēr `'tracking'` atskaitē, kas iegūta patstāvīgi ar `tracking.get`, `tracking.list` vai `emails.getTracking`. Tā pati atskaite, ieligzdota kā `email.tracking` iegūtā ziņojumā, atnāk bez šīs atslēgas, jo tur tā ir daļa no šī objekta, nevis kaut kas atsevišķi iegūts.
idstring- Izsekošanas ieraksta paša id, `tmsg_…`. Tieši pēc tā darbojas izsaukumi `listOpens` un `listClicks` par atsevišķiem trāpījumiem; tiem padots `msg_…` vispirms tiek atrisināts uz šo.
sendIdstring | null- `msg_…` sūtījums, ar kuru šis korelē, un null tur, kur sūtījuma ieraksts netika rakstīts. Rakstīšanas logs, MCP `sendEmail` un asistents sūta bez tāda. Izsekošana aptver pastkasti, nevis tikai API datplūsmu.
threadIdstring | null- Aizpildīts pēc nosūtīšanas, lai lasīšanas saskarne varētu ziņojumu atkal atrast, un null, ja draiveris neko neuzrādīja. Nav kritisks: ieraksts, kurā tas ir null, joprojām tiek ieskaitīts.
messageIdstring | null- RFC 5322 Message-ID, nevis mūsu id. Arī tas tiek aizpildīts pēc nosūtīšanas un ir null, ja transports neko neatgrieza, ar ko to aizpildīt.
subjectstring | null- Temats tāds, kāds tas bija nosūtīšanas brīdī. Null ziņojumam, kas ierakstīts bez tā.
fromstring- Nosūtītāja adrese, iekopēta ierakstā, nevis pievienota no sūtījuma. Pārskatus lasa ilgi pēc notikuma, un adrese, kas kopš tā laika izlabota vai noņemta, citādi pārrakstītu vēsturi.
sourceEmailSource | (string & {})- Kura virsma to nosūtīja: `composer`, `api`, `mcp`, `ai` vai `queue`. Tips ir atvērts, tāpēc virsma, ko šis SDK vēl nenosauc, nav savietojamību lauzošas izmaiņas.
sentAtstring | null- Kad ziņojums aizgāja, kā ISO-8601 moments. Null ierakstam, kura sūtīšana nekad netika pabeigta. `tracking.list` tādus izslēdz, `get` — nē.
opensboolean- Vai šim ziņojumam tika PIEMĒROTS pikselis. Tas ir tas, kas tika izdarīts, nevis tas, ko tagad saka konta iestatījums.
clicksboolean- Vai šī ziņojuma saites tika pārrakstītas. False, kad pamattekstā nebija saišu, jo tad nekas netika mainīts un ierakstu ar pretēju apgalvojumu nevarētu saskaņot ar baitiem.
openedboolean- Vai visās kopijās tika reģistrēta kaut viena ieskaitīta atvēršana. Lasiet to kopā ar `opens`: datu trūkums tāpēc, ka nekas netika vākts, ir cits fakts nekā tas, ka neviens ziņojumu nav lasījis.
clickedboolean- Vai tika reģistrēts kaut viens ieskaitīts klikšķis. Spēcīgāks pierādījums nekā atvēršana, jo attēli tiek bloķēti daudz biežāk, nekā saites paliek neatvērtas.
attributableboolean- Vai katru lasīšanu šeit var piesaistīt konkrētam nosauktam adresātam. False tajā mirklī, kad kāda nepiesaistīta kopija uzrāda ieskaitītu aktivitāti, un tas ir vairāku adresātu gadījums, kad viens pamatteksts aiziet visam sarakstam ar vienu marķieri, tāpēc pārbaudiet to, pirms rakstāt „Bobs to nav atvēris“.
openCountnumber- Atvēršanas, kuras, domājams, izraisījis cilvēks, saskaitītas pa kopijām. Mašīnu trāpījumi tiek izslēgti, un atkārtojumi trīsdesmit sekunžu laikā sakļaujas vienā, tāpēc šis ir tas skaitlis, ko rādīt lasītājam.
clickCountnumber- Ieskaitītie klikšķi, saskaitīti pa kopijām. Dublikāti tiek atmesti katrai saitei atsevišķi, nevis katram ziņojumam, tāpēc divas dažādas saites, kurām sekots ar dažu sekunžu starpību, ir divi klikšķi.
openCountRawnumber- Katra pikseļa ielāde, ieskaitot skenerus un privātuma starpniekus. `openCountRaw - openCount` ir tas, cik klasifikators atlika malā, un vienīgais pieejamais pierādījums, ka filtrēšana vispār notika.
clickCountRawnumber- Katrs pārrakstītas saites apmeklējums, ieskaitot mašīnu trāpījumus un atkārtojumus.
firstOpenAtstring | null- Agrākā ieskaitītā atvēršana visās kopijās, un null, kamēr tādas nav. Mašīnu trāpījumi to nekad nepārbīda.
lastOpenAtstring | null- Jaunākā ieskaitītā atvēršana visās kopijās, null, kamēr tādas nav.
firstClickAtstring | null- Agrākais ieskaitītais klikšķis visās kopijās, null, kamēr tāda nav.
lastClickAtstring | null- Jaunākais ieskaitītais klikšķis visās kopijās, null, kamēr tāda nav.
recipientsTrackingRecipientResource[]- Viens ieraksts katrai izsekotajai kopijai: katram adresātam tur, kur transports ļauj baitiem atšķirties katram cilvēkam, un viens kopīgs ieraksts tur, kur neļauj. Kopīgais ieraksts tiek nomests, ja vien uz tā patiešām kaut kas nav nonācis, tāpēc neaiztikta „kāds“ rinda nekad nestāv līdzās īstiem vārdiem.
recipients[].emailstring | null- Kam šī kopija tika sūtīta, mazajiem burtiem un tā, kā tas bija sūtīšanas brīdī. Null tieši tad, kad `attributed` ir false.
recipients[].kind'to' | 'cc' | 'bcc' | null- Kurā galvenē adrese parādījās, lai atskaite lasītos tāpat kā ziņojums. Null kopīgajā kopijā, kas nepieder nevienai atsevišķai adresei.
recipients[].attributedboolean- Vai šī rinda nosauc cilvēku. Lasiet to pirms `email`: false ir kopīgā kopija, kas tiek uzskaitīta, tiklīdz uz tās nonāk kaut viens trāpījums, un vārda piešķiršana šim trāpījumam, pat ziņojumā ar vienu adresātu, izdomātu tieši to vienu faktu, ko mehānisms nevar sniegt.
recipients[].openCountnumber- Ieskaitītās atvēršanas tikai šai kopijai, ar tiem pašiem izņēmumiem, kas ziņojuma kopsummai: mašīnu trāpījumi nomesti un atkārtojumi trīsdesmit sekunžu laikā sakļauti vienā.
recipients[].clickCountnumber- Ieskaitītie klikšķi tikai šai kopijai, dublikātus atmetot katrai saitei atsevišķi, nevis katrai kopijai.
recipients[].firstOpenAtstring | null- Agrākā ieskaitītā atvēršana šajā kopijā, null, kamēr tādas nav.
recipients[].lastOpenAtstring | null- Jaunākā ieskaitītā atvēršana šajā kopijā, null, kamēr tādas nav.
recipients[].firstClickAtstring | null- Agrākais ieskaitītais klikšķis uz šīs kopijas; null, kamēr tāda nav.
recipients[].lastClickAtstring | null- Jaunākais ieskaitītais klikšķis uz šīs kopijas; null, kamēr tāda nav.
linksTrackingLinkResource[]- Katra saite, kas šajā ziņojumā tika pārrakstīta, sakārtota pēc tās vietas pamattekstā. Tukšs, ja tādu nebija: ziņojums, kas nosūtīts ar izslēgtu `clicks`, vai tāds, kura tekstā vispār nebija nevienas saites.
links[].idstring- Pašas saites id, `lnk_…`. Tā ir vērtība, ko nosauc klikšķa ieraksta `linkId`, tāpēc `listClicks` atgriezto apmeklējumu var saskaņot ar šo ierakstu.
links[].urlstring- Kurp saite patiesībā ved — tāda, kāda tā bija ziņojumā pirms pārrakstīšanas. Novirzītājs no id atrisina atpakaļ šo adresi un nosūta apmeklētāju tālāk.
links[].labelstring | null- Saites teksts tāds, kāds tas parādījās ziņojumā, vai null, ja saitei tāda nebija, piemēram, attēlam vai kailai URL. Tas ir tāpēc, lai pārskatā varētu rakstīt “cenu lapas saite”, nevis citēt URL ar trim izsekošanas parametriem, un tas nekad neaizstāj `url`.
links[].clickCountnumber- Ieskaitītie apmeklējumi šai saitei, summēti pa kopijām. Katrai saitei ir tas pats trīsdesmit sekunžu logs, kas ziņojuma `clickCount`.
links[].clickCountRawnumber- Katrs šīs saites apmeklējums, ieskaitot mašīnu pieprasījumus un atkārtojumus.