SDK
Öffnungs- und Klick-Tracking
`emails.getTracking` und die gesamte `tracking`-Ressource.
Eine Nachricht
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)Eine nie getrackte Nachricht wirft einen OpenEmailApiError, dessen isNotFound true ist, und liefert keinen leeren Bericht. "Wir haben nichts erfasst" und "niemand hat sie geöffnet" sind verschiedene Antworten und dürfen sich keine Response teilen.
Über das gesamte Postfach
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 und listClicks lösen zu einfachen arrays auf. get, listOpens und listClicks nehmen entweder die Versand-id msg_… oder die eigene tmsg_… des Tracking-Datensatzes entgegen.
Eine eigene Ressource statt Feldern an emails, und der Grund ist die Abdeckung: emails listet Versanddatensätze auf, die nur für Mail existieren, die diese API bearbeitet hat. Der Composer, die MCP-Werkzeuge und der Assistent senden alle ohne einen solchen, ein Bericht auf Basis von emails wäre daher ein Bericht über Ihren API-Verkehr und nicht über das Postfach.
Die Zahlen ehrlich lesen
| Paar | Was es bedeutet |
|---|---|
| `opens` / `clicks` | Was ANGEWENDET wurde: ob die Nachricht mit einem Pixel oder mit umgeschriebenen Links hinausging. |
| `opened` / `clicked` | Was geschehen ist. |
| `openCount` | Gezählte Zugriffe. Scanner und Datenschutz-Proxys ausgeschlossen. |
| `openCountRaw` | Jeder Zugriff. Diesen Wert als Interaktion anzuführen ist der Weg zu einer Öffnungsrate über 100 %. |
| `attributable` | Ob sich ein Lesevorgang überhaupt einem namentlich genannten Empfänger zuordnen lässt. |
Raten aus tracking.getStats beziehen sich auf GETRACKTE Nachrichten, nie auf alles Gesendete. Andernfalls sähe ein Postfach, das jede zehnte Nachricht trackt, wie eingebrochen aus.
Parameter: tracking.list
openedboolean- `true` wählt Nachrichten mit mindestens einer gezählten Öffnung, `false` wählt getrackte Nachrichten ohne eine solche. Keines von beiden ist Standard, und `false` bedeutet nie ungetrackte Mail, die in dieser Liste überhaupt nicht erscheint.
clickedboolean- Derselbe Filter für gezählte Klicks, unabhängig von `opened` angewendet. Beide dürfen angegeben werden, und Nachrichten müssen beide erfüllen.
daysnumber- Wie viele Tage ab jetzt zurückgeblickt wird, 1 bis 365, Standard 30; außerhalb dieses Bereichs ergibt es ein 422. Das Fenster bemisst sich am Erstellungszeitpunkt des Tracking-Datensatzes, und aufgeführt werden nur Datensätze, deren Versand tatsächlich hinausging.
limitnumber- Höchstens so viele Nachrichten, 1 bis 200, Standard 50, neueste zuerst. Es gibt keinen cursor: Dies ist ein Bericht über ein Zeitfenster und kein Feed, er ist daher durch `days` und `limit` begrenzt und wird als Ganzes gelesen.
Antwort: TrackingResource
object'tracking'- Immer `'tracking'` bei einem eigenständig abgerufenen Bericht, über `tracking.get`, `tracking.list` oder `emails.getTracking`. Derselbe Bericht, als `email.tracking` in einer abgerufenen Nachricht verschachtelt, kommt ohne diesen Schlüssel, denn dort ist er Teil jenes Objekts und nicht etwas, das abgerufen wurde.
idstring- Die eigene id des Tracking-Datensatzes, `tmsg_…`. Auf sie sind die Aufrufe `listOpens` und `listClicks` je Zugriff geschlüsselt; eine ihnen übergebene `msg_…` wird zuerst hierauf aufgelöst.
sendIdstring | null- Der Versand `msg_…`, zu dem dies gehört, und null, wenn kein Versanddatensatz geschrieben wurde. Der Composer, `sendEmail` von MCP und der Assistent senden alle ohne einen solchen. Das Tracking umfasst das Postfach, nicht nur den API-Verkehr.
threadIdstring | null- Wird nach der Übertragung gefüllt, damit eine lesende Oberfläche die Nachricht wiederfindet, und null, wenn der Treiber keine gemeldet hat. Nicht tragend: Ein Datensatz, bei dem der Wert null ist, zählt trotzdem.
messageIdstring | null- Die Message-ID nach RFC 5322, nicht unsere id. Ebenfalls nach der Übertragung gefüllt, und null, wenn der Transport nichts zurückgab, womit sie zu füllen wäre.
subjectstring | null- Der Betreff im Stand zum Versandzeitpunkt. Null bei einer Nachricht, die ohne Betreff erfasst wurde.
fromstring- Die Absenderadresse, auf den Datensatz kopiert statt aus dem Versand hinzugejoint. Berichte werden lange nach dem Ereignis gelesen, und eine seither korrigierte oder entfernte Adresse würde sonst die Geschichte umschreiben.
sourceEmailSource | (string & {})- Welche Oberfläche sie gesendet hat: `composer`, `api`, `mcp`, `ai` oder `queue`. Offen typisiert, damit eine Oberfläche, die dieses SDK noch nicht benennt, keine Breaking Change ist.
sentAtstring | null- Wann die Nachricht hinausging, als ISO-8601-Zeitpunkt. Null bei einem Datensatz, dessen Versand nie abgeschlossen wurde. `tracking.list` schließt diese aus, `get` nicht.
opensboolean- Ob auf diese Nachricht ein Pixel ANGEWENDET wurde. Dies ist, was getan wurde, nicht was die Kontoeinstellung jetzt sagt.
clicksboolean- Ob die Links dieser Nachricht umgeschrieben wurden. False, wenn der Body keine Links enthielt, denn dann wurde nichts geändert und ein Datensatz, der das Gegenteil behauptet, ließe sich nicht mit den Bytes in Einklang bringen.
openedboolean- Ob über die Kopien hinweg irgendeine gezählte Öffnung erfasst wurde. Lesen Sie es zusammen mit `opens`: keine Daten, weil keine erhoben wurden, ist etwas anderes als niemand, der die Nachricht gelesen hat.
clickedboolean- Ob irgendein gezählter Klick erfasst wurde. Ein stärkerer Beleg als eine Öffnung, da Bilder weit häufiger blockiert werden, als Links ungeklickt bleiben.
attributableboolean- Ob sich hier jeder Lesevorgang einem namentlich genannten Empfänger zuordnen lässt. False in dem Moment, in dem eine nicht zugeordnete Kopie gezählte Aktivität zeigt, also im Fall mehrerer Empfänger, bei dem ein Body unter einem einzigen Token an die gesamte Liste geht; prüfen Sie es daher, bevor Sie "Bob hat dies nicht geöffnet" schreiben.
openCountnumber- Öffnungen, die mutmaßlich von einem Menschen ausgelöst wurden, summiert über die Kopien. Maschinelle Zugriffe sind ausgeschlossen und Wiederholungen innerhalb von dreißig Sekunden werden zu einer zusammengefasst, dies ist daher die Zahl, die man einem Leser vorlegt.
clickCountnumber- Gezählte Klicks, summiert über die Kopien. Dedupliziert pro Link und nicht pro Nachricht, zwei verschiedene Links im Abstand von Sekunden sind daher zwei Klicks.
openCountRawnumber- Jeder Pixelabruf, Scanner und Datenschutz-Proxys eingeschlossen. `openCountRaw - openCount` ist die Zahl derer, die der Klassifikator aussortiert hat, und der einzige verfügbare Beleg dafür, dass überhaupt gefiltert wurde.
clickCountRawnumber- Jeder Aufruf eines umgeschriebenen Links, maschinelle Zugriffe und Wiederholungen eingeschlossen.
firstOpenAtstring | null- Die früheste gezählte Öffnung über die Kopien, und null, solange es keine gibt. Maschinelle Zugriffe verschieben sie nie.
lastOpenAtstring | null- Die jüngste gezählte Öffnung über die Kopien, null, solange es keine gibt.
firstClickAtstring | null- Der früheste gezählte Klick über die Kopien, null, solange es keinen gibt.
lastClickAtstring | null- Der jüngste gezählte Klick über die Kopien, null, solange es keinen gibt.
recipientsTrackingRecipientResource[]- Ein Eintrag pro getrackter Kopie: pro Empfänger, wo der Transport unterschiedliche Bytes je Person zulässt, und ein einzelner gemeinsamer Eintrag, wo er das nicht tut. Der gemeinsame Eintrag entfällt, sofern nicht tatsächlich etwas darauf eingegangen ist, eine unberührte "Irgendwer"-Zeile steht daher nie neben echten Namen.
recipients[].emailstring | null- An wen diese Kopie ging, in Kleinbuchstaben und im Stand zum Versandzeitpunkt. Genau dann null, wenn `attributed` false ist.
recipients[].kind'to' | 'cc' | 'bcc' | null- Auf welchem Header die Adresse stand, damit sich ein Bericht so liest wie die Nachricht. Null bei der gemeinsamen Kopie, die zu keiner einzelnen Adresse gehört.
recipients[].attributedboolean- Ob diese Zeile eine Person benennt. Lesen Sie sie vor `email`: false ist die gemeinsame Kopie, die aufgeführt wird, sobald irgendein Zugriff auf sie eingeht, und diesem Zugriff einen Namen zu geben, selbst bei einer Nachricht mit einem einzigen Empfänger, würde genau die Tatsache erfinden, die der Mechanismus nicht liefern kann.
recipients[].openCountnumber- Gezählte Öffnungen allein auf dieser Kopie, unter denselben Ausschlüssen wie bei der Gesamtzahl der Nachricht: maschinelle Zugriffe verworfen, Wiederholungen innerhalb von dreißig Sekunden zu einer zusammengefasst.
recipients[].clickCountnumber- Gezählte Klicks allein auf dieser Kopie, dedupliziert pro Link und nicht pro Kopie.
recipients[].firstOpenAtstring | null- Die früheste gezählte Öffnung auf dieser Kopie, null, solange es keine gibt.
recipients[].lastOpenAtstring | null- Die jüngste gezählte Öffnung auf dieser Kopie, null, solange es keine gibt.
recipients[].firstClickAtstring | null- Der früheste gezählte Klick auf dieser Kopie, null, solange es keinen gibt.
recipients[].lastClickAtstring | null- Der jüngste gezählte Klick auf dieser Kopie, null, solange es keinen gibt.
linksTrackingLinkResource[]- Jeder Link, der in dieser Nachricht umgeschrieben wurde, geordnet nach seiner Position im Body. Leer, wenn keiner umgeschrieben wurde: eine Nachricht, die mit abgeschaltetem `clicks` gesendet wurde, oder eine, deren Body überhaupt keinen Link enthielt.
links[].idstring- Die eigene id des Links, `lnk_…`. Sie ist der Wert, den `linkId` einer Klickzeile nennt, ein Zugriff aus `listClicks` lässt sich daher dem Eintrag hier wieder zuordnen.
links[].urlstring- Wohin der Link tatsächlich führt, so wie er vor dem Umschreiben in der Nachricht stand. Der Redirector löst eine id hierauf zurück auf und leitet den Besucher weiter.
links[].labelstring | null- Der Linktext, wie er in der Nachricht erschien, oder null, wenn der Link keinen hatte, etwa bei einem Bild oder einer blanken URL. Er ist da, damit ein Bericht "der Preis-Link" sagen kann, statt eine URL mit drei Tracking-Parametern zu zitieren, und er ersetzt nie `url`.
links[].clickCountnumber- Gezählte Aufrufe dieses Links, summiert über die Kopien. Dasselbe Dreißig-Sekunden-Fenster pro Link wie bei `clickCount` an der Nachricht.
links[].clickCountRawnumber- Jeder Aufruf dieses Links, maschinelle Zugriffe und Wiederholungen eingeschlossen.