Ruby

Öffnungs- und Klick-Tracking

`emails.get_tracking` und der gesamte Namespace `tracking`.

Eine Nachricht

tracking.rb

report = client.emails.get_tracking("msg_3f9a1c07d2b84e6a9c5b1f20") puts "#{report[:openCount]} opens from #{report[:recipients].size} recipients"report[:links].each { |link| puts "#{link[:url]} #{link[:clickCount]}" }

Eine nie getrackte Nachricht löst einen OpenEmail::NotFoundError aus, dessen not_found? true ist, und liefert keinen leeren Bericht. „Wir haben nichts erfasst“ und „niemand hat sie geöffnet“ sind verschiedene Antworten und dürfen nicht dieselbe Response ergeben. Eine mit einem Testschlüssel gesendete Nachricht wird nie getrackt und löst daher immer einen solchen Fehler aus.

Über das gesamte Postfach

tracking_report.rb

client.tracking.list(opened: false, days: 7, limit: 100)client.tracking.get_stats(days: 30, offset_minutes: Time.now.utc_offset / 60)client.tracking.get("msg_3f9a1c07d2b84e6a9c5b1f20")client.tracking.list_opens("msg_3f9a1c07d2b84e6a9c5b1f20", include_machine: true)client.tracking.list_clicks("msg_3f9a1c07d2b84e6a9c5b1f20")

list, list_opens und list_clicks geben eine OpenEmail::Page zurück, und list_all, iterate, list_all_opens, iterate_opens, list_all_clicks und iterate_clicks durchlaufen alle Seiten für Sie. get, list_opens und list_clicks nehmen entweder die Versand-id msg_… oder die eigene tmsg_… des Tracking-Datensatzes entgegen.

Ein eigener Namespace statt Methoden 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-Tools 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 und clicks	Was ANGEWENDET wurde: ob die Nachricht mit einem Pixel oder mit umgeschriebenen Links hinausging.
opened und 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.get_stats beziehen sich auf GETRACKTE Nachrichten, nie auf alles Gesendete. Andernfalls sähe ein Postfach, das jede zehnte Nachricht trackt, wie eingebrochen aus. openRate und clickRate sind Prozentwerte, auf eine Nachkommastelle gerundet, etwa 42.5, keine Brüche zwischen 0 und 1.

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.
daysInteger: Wie viele Tage ab jetzt zurückgeblickt wird, 1 bis 365, Standard 30, und außerhalb dieses Bereichs ergibt es einen 422. Das Fenster bemisst sich am Erstellungszeitpunkt des Tracking-Datensatzes, und aufgeführt werden nur Datensätze, deren Versand tatsächlich hinausging.
minutesInteger: Das Fenster stattdessen in Minuten, von 1 bis 527040, mit Vorrang vor `days`, wenn beide gesetzt sind. Ein Fenster unter einem Tag braucht ein feineres `grain`.
grainString: `minute`, `hour` oder `day`, Standard `day`. Es rundet nur den Beginn des Fensters ab, damit diese Liste zu `get_stats` mit derselben Körnung passt, und formt nichts an der Antwort.
limitInteger: Berichte pro Seite, 1 bis 200, Standard 50, neueste zuerst. Übergeben Sie den `next_cursor` der Seite mit denselben Filtern als `cursor:`, um die nächste zu erhalten, oder lassen Sie `list_all` und `iterate` das ganze Fenster durchlaufen.
cursorString: Der `next_cursor` der vorherigen Seite, eine `tmsg_`-id.
api_keyString: Listet mit diesem Schlüssel statt mit dem des Clients auf.

Antwort: der Tracking-Bericht

emails.get_tracking und tracking.get geben einen Bericht als Hash mit Symbol-Schlüsseln zurück, und tracking.list gibt eine Seite davon zurück.

objectString: Immer `tracking` bei einem eigenständig abgerufenen Bericht, über `tracking.get`, `tracking.list` oder `emails.get_tracking`. Derselbe Bericht, als `tracking` in einer Nachricht aus `emails.get` verschachtelt, kommt ohne diesen Schlüssel, denn dort ist er Teil dieser Nachricht und nicht etwas, das abgerufen wurde.
idString: Die eigene id des Tracking-Datensatzes, `tmsg_…`. Auf sie sind `list_opens` und `list_clicks` geschlüsselt, und eine ihnen übergebene `msg_…` wird zuerst hierauf aufgelöst.
sendIdString or nil: Der Versand `msg_…`, zu dem dies gehört, und nil, 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 or nil: Wird nach der Übertragung gefüllt, damit eine lesende Oberfläche die Nachricht wiederfindet, und nil, wenn der Treiber keine gemeldet hat. Nicht tragend: Ein Datensatz, bei dem der Wert nil ist, zählt trotzdem.
messageIdString or nil: Die Message-ID nach RFC 5322, nicht unsere id. Ebenfalls nach der Übertragung gefüllt, und nil, wenn der Transport nichts zurückgab, womit sie zu füllen wäre.
subjectString or nil: Der Betreff im Stand zum Versandzeitpunkt. nil 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.
sourceString: Welche Oberfläche sie gesendet hat: `composer`, `api`, `mcp`, `ai` oder `queue`. Eine Oberfläche, die dieses Gem noch nicht benennt, kann auftauchen. Behandeln Sie einen unbekannten Wert daher als Information und nicht als Fehler.
sentAtString or nil: Wann die Nachricht hinausging, als Zeitpunkt nach ISO 8601. nil bei einem Datensatz, dessen Versand nie abgeschlossen wurde. `tracking.list` lässt 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.
openCountInteger: Ö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.
clickCountInteger: 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.
openCountRawInteger: Jeder Pixelabruf, Scanner und Datenschutz-Proxys eingeschlossen. `openCountRaw` minus `openCount` ist die Zahl der aussortierten Abrufe, maschinelle Abrufe und Wiederholungen innerhalb von dreißig Sekunden zusammen, und der einzige verfügbare Beleg dafür, dass überhaupt gefiltert wurde.
clickCountRawInteger: Jeder Aufruf eines umgeschriebenen Links, maschinelle Zugriffe und Wiederholungen eingeschlossen.
firstOpenAtString or nil: Die früheste gezählte Öffnung über alle Kopien, und nil, solange es keine gibt. Maschinelle Zugriffe verschieben sie nie.
lastOpenAtString or nil: Die jüngste gezählte Öffnung über die Kopien, nil, solange es keine gibt.
firstClickAtString or nil: Der früheste gezählte Klick über die Kopien, nil, solange es keinen gibt.
lastClickAtString or nil: Der jüngste gezählte Klick über die Kopien, nil, solange es keinen gibt.
recipientsArray<Hash>: 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.
linksArray<Hash>: 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.

Jeder Eintrag in recipients

emailString or nil: An wen diese Kopie ging, in Kleinbuchstaben und im Stand zum Versandzeitpunkt. Genau dann nil, wenn `attributed` false ist.
kindString or nil: `to`, `cc` oder `bcc`: auf welchem Header die Adresse stand, damit sich ein Bericht so liest wie die Nachricht. nil bei der gemeinsamen Kopie, die zu keiner einzelnen Adresse gehört.
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.
openCountInteger: 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.
clickCountInteger: Gezählte Klicks allein auf dieser Kopie, dedupliziert pro Link und nicht pro Kopie.
firstOpenAtString or nil: Die früheste gezählte Öffnung auf dieser Kopie, nil, solange es keine gibt.
lastOpenAtString or nil: Die jüngste gezählte Öffnung auf dieser Kopie, nil, solange es keine gibt.
firstClickAtString or nil: Der früheste gezählte Klick auf dieser Kopie, nil, solange es keinen gibt.
lastClickAtString or nil: Der jüngste gezählte Klick auf dieser Kopie, nil, solange es keinen gibt.

Jeder Eintrag in links

idString: Die eigene id des Links, `lnk_…`. Sie ist der Wert, den `linkId` einer Klickzeile nennt, ein Zugriff aus `list_clicks` lässt sich daher dem Eintrag hier wieder zuordnen.
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 auf und leitet den Besucher weiter.
labelString or nil: Der Linktext, wie er in der Nachricht erschien, oder nil, wenn der Link keinen hatte, etwa bei einem Bild oder einer bloßen 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`.
clickCountInteger: Gezählte Aufrufe dieses Links, summiert über die Kopien. Dasselbe Dreißig-Sekunden-Fenster pro Link wie bei `clickCount` an der Nachricht.
clickCountRawInteger: Jeder Aufruf dieses Links, maschinelle Zugriffe und Wiederholungen eingeschlossen.