Ruby

Açılma ve tıklama izleme

`emails.get_tracking` ve `tracking` ad alanının tamamı.

Tek mesaj

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]}" }

Hiç izlenmemiş bir ileti boş bir rapor değil, not_found? değeri true olan bir OpenEmail::NotFoundError fırlatır. “Hiçbir şey kaydetmedik” ile “kimse açmadı” farklı yanıtlardır ve aynı yanıtı paylaşmamalıdır. Bir test anahtarıyla gönderilen ileti asla izlenmez, bu yüzden her zaman bu hatayı fırlatır.

Posta kutusu genelinde

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 ve list_clicks bir OpenEmail::Page döndürür; list_all, iterate, list_all_opens, iterate_opens, list_all_clicks ve iterate_clicks ise her sayfayı sizin için dolaşır. get, list_opens ve list_clicks, msg_… gönderim kimliğini ya da izleme kaydının kendi tmsg_… kimliğini alır.

emails üzerindeki metotlar yerine kendi başına bir ad alanı olmasının nedeni kapsamdır: emails, yalnızca bu API'nin işlediği postalar için var olan gönderim kayıtlarını listeler. Yazma ekranı, MCP araçları ve asistan bu kayıt olmadan gönderim yapar; dolayısıyla emails üzerine kurulu bir rapor, posta kutusu hakkında değil, API trafiğiniz hakkında bir rapor olurdu.

Sayıları dürüstçe okumak

Çift	Ne anlama gelir
opens ve clicks	UYGULANAN şey: mesajın bir pikselle veya yeniden yazılmış bağlantılarla gidip gitmediği.
opened ve clicked	Ne olduğu.
openCount	Sayılan istekler. Tarayıcı botları ve gizlilik vekilleri hariç.
openCountRaw	Her istek. Bunu etkileşim diye sunmak, açılma oranının %100'ü aşmasına yol açar.
attributable	Bir okumanın adı belli bir alıcıya bağlanıp bağlanamayacağı.

tracking.get_stats oranları, gönderilen her şey üzerinden değil, İZLENEN iletiler üzerinden hesaplanır. Aksi hâlde on iletiden birini izleyen bir posta kutusu çökmüş gibi görünürdü. openRate ve clickRate, 0 ile 1 arasında kesirler değil, 42.5 gibi tek ondalık basamağa yuvarlanmış yüzdelerdir.

Parametreler: tracking.list

openedBoolean: `true`, en az bir sayılan açılması olan mesajları seçer; `false` ise hiç açılması olmayan izlenmiş mesajları seçer. Hiçbiri varsayılan değildir ve `false` asla izlenmemiş posta anlamına gelmez; o postalar bu listede hiç yer almaz.
clickedBoolean: Sayılan tıklamalar için aynı filtre; `opened` filtresinden bağımsız uygulanır. İkisi birden verilebilir ve mesajların ikisini de sağlaması gerekir.
daysInteger: Şu andan geriye kaç gün bakılacağı; 1 ile 365 arası, varsayılanı 30. Bu aralığın dışı 422 verir. Pencere, izleme kaydının oluşturulduğu zamana göre ölçülür ve yalnızca gönderimi gerçekten çıkmış kayıtlar listelenir.
minutesInteger: Bunun yerine dakika cinsinden pencere; 1 ile 527040 arası. İkisi de ayarlandığında `days` değerine üstün gelir. Bir günden kısa bir pencere daha ince bir `grain` gerektirir.
grainString: `minute`, `hour` ya da `day`; varsayılanı `day`. Yalnızca pencerenin başlangıcını aşağı yuvarlar; böylece bu liste aynı ayrıntı düzeyinde okunan `get_stats` ile eşleşir ve yanıtta hiçbir şeyi biçimlendirmez.
limitInteger: Sayfa başına rapor; 1 ile 200 arası, varsayılanı 50, en yeniler önce. Sonraki sayfa için sayfanın `next_cursor` değerini aynı filtrelerle `cursor:` olarak geri geçirin ya da pencerenin tamamını `list_all` ve `iterate` dolaşsın.
cursorString: Önceki sayfanın `next_cursor` değeri, bir `tmsg_` kimliği.
api_keyString: İstemcinin anahtarı yerine bu anahtarla listeler.

Yanıt: izleme raporu

emails.get_tracking ve tracking.get tek bir raporu Symbol anahtarlı bir Hash olarak döndürür, tracking.list ise bunlardan oluşan bir sayfa döndürür.

objectString: `tracking.get`, `tracking.list` ya da `emails.get_tracking` üzerinden kendi başına getirilen bir raporda her zaman `tracking`. `emails.get` ile gelen bir iletide `tracking` olarak iç içe yer alan aynı rapor bu anahtar olmadan gelir, çünkü orada ayrıca getirilmiş bir şey değil, o iletinin bir parçasıdır.
idString: İzleme kaydının kendi kimliği, `tmsg_…`. `list_opens` ve `list_clicks` bu kimliğe göre çalışır ve onlara verilen bir `msg_…` önce bu kimliğe çözümlenir.
sendIdString or nil: Bu raporun ilişkili olduğu `msg_…` gönderimi; gönderim kaydı yazılmamışsa nil. Yazma ekranı, MCP'nin `sendEmail` aracı ve asistan bu kayıt olmadan gönderim yapar. İzleme yalnızca API trafiğini değil, posta kutusunu kapsar.
threadIdString or nil: Okuma arayüzünün iletiyi yeniden bulabilmesi için iletimden sonra doldurulur; sürücü bir değer bildirmediyse nil. Kritik değildir: bu alanı nil olan bir kayıt da sayılır.
messageIdString or nil: Bizim kimliğimiz değil, RFC 5322 Message-ID. Bu da iletimden sonra doldurulur; taşıma katmanı onu dolduracak bir şey döndürmediyse nil.
subjectString or nil: Gönderim anındaki hâliyle konu. Konusuz kaydedilmiş bir iletide nil.
fromString: Gönderen adres; gönderimden birleştirilmek yerine kaydın üzerine kopyalanır. Raporlar olaydan çok sonra okunur ve o zamandan beri düzeltilmiş veya kaldırılmış bir adres, aksi hâlde geçmişi yeniden yazardı.
sourceString: İletiyi hangi yüzeyin gönderdiği: `composer`, `api`, `mcp`, `ai` ya da `queue`. Bu gem'in henüz adlandırmadığı bir yüzey de görünebilir; bu yüzden bilinmeyen bir değeri bir hata olarak değil, bir bilgi olarak ele alın.
sentAtString or nil: İletinin gittiği an, ISO 8601 anı olarak. Gönderimi hiç tamamlanmamış bir kayıtta nil. `tracking.list` bunları dışarıda bırakır, `get` bırakmaz.
opensBoolean: Bu mesaja bir pikselin UYGULANIP uygulanmadığı. Bu, hesap ayarının şu anda ne dediği değil, ne yapıldığıdır.
clicksBoolean: Bu iletinin bağlantılarının yeniden yazılıp yazılmadığı. Gövde hiç bağlantı taşımıyorsa false, çünkü o durumda hiçbir şey değişmemiştir ve aksini iddia eden bir kayıt baytlarla bağdaştırılamazdı.
openedBoolean: Kopyalar genelinde sayılan herhangi bir açılma kaydedilip kaydedilmediği. Bunu `opens` ile birlikte okuyun: veri toplanmadığı için verinin olmaması ile kimsenin mesajı okumamış olması farklı olgulardır.
clickedBoolean: Sayılan herhangi bir tıklama kaydedilip kaydedilmediği. Bir açılmadan daha güçlü bir kanıttır, çünkü görseller, bağlantıların takip edilmemesinden çok daha sık engellenir.
attributableBoolean: Buradaki her okumanın adı belli bir alıcıya bağlanıp bağlanamadığı. Atfedilmemiş bir kopyada sayılan bir etkinlik göründüğü anda false olur; bu, tek bir gövdenin tek bir belirteç altında tüm listeye gittiği çok alıcılı durumdur. Bu yüzden “Bob bunu açmadı” yazmadan önce bunu denetleyin.
openCountInteger: Bir insanın yol açtığına inanılan açılmalar, kopyalar üzerinden toplanır. Makine istekleri hariç tutulur ve otuz saniye içindeki tekrarlar tek bir açılmaya indirgenir; dolayısıyla okuyucunun önüne konacak rakam budur.
clickCountInteger: Sayılan tıklamalar, kopyalar üzerinden toplanır. Mesaj başına değil bağlantı başına tekilleştirilir; dolayısıyla saniyeler arayla takip edilen iki farklı bağlantı iki tıklamadır.
openCountRawInteger: Güvenlik tarayıcıları ve gizlilik proxy'leri dahil her piksel getirme. `openCountRaw` eksi `openCount`, kenara ayrılanların sayısıdır (makine getirmeleri ve otuz saniye içindeki tekrarlar birlikte) ve filtrelemenin gerçekleştiğine dair elde bulunan tek kanıttır.
clickCountRawInteger: Yeniden yazılmış bir bağlantıya yapılan her ziyaret; makine istekleri ve tekrarlar dahil.
firstOpenAtString or nil: Kopyalar genelinde sayılan en erken açılma; hiç yokken nil. Makine erişimleri onu asla değiştirmez.
lastOpenAtString or nil: Kopyalar genelinde sayılan en son açılma; hiç yokken nil.
firstClickAtString or nil: Kopyalar genelinde sayılan en erken tıklama; hiç yokken nil.
lastClickAtString or nil: Kopyalar genelinde sayılan en son tıklama; hiç yokken nil.
recipientsArray<Hash>: İzlenen her kopya için bir kayıt: taşıma katmanı baytların kişi başına farklılaşmasına izin verdiğinde alıcı başına, izin vermediğinde ise tek bir paylaşılan kayıt. Paylaşılan kayıt, üzerine gerçekten bir şey düşmedikçe atılır; böylece dokunulmamış bir “birisi” satırı asla gerçek adların yanında durmaz.
linksArray<Hash>: Bu mesajda yeniden yazılan her bağlantı, gövdedeki konumuna göre sıralı. Hiç yoksa boştur: `clicks` kapalı gönderilmiş bir mesaj ya da gövdesinde hiç bağlantı olmayan bir mesaj.

recipients içindeki her kayıt

emailString or nil: Bu kopyanın kime gittiği; küçük harfe çevrilmiş ve gönderim anındaki hâliyle. Tam olarak `attributed` false olduğunda nil.
kindString or nil: `to`, `cc` ya da `bcc`: adresin hangi başlıkta yer aldığı; böylece rapor iletiyle aynı biçimde okunur. Tek bir adrese ait olmayan ortak kopyada nil.
attributedBoolean: Bu satırın bir kişiyi adlandırıp adlandırmadığı. `email` alanından önce bunu okuyun: false, üzerine herhangi bir istek düştüğü anda listelenen paylaşılan kopyadır ve tek alıcılı bir mesajda bile o isteğe bir ad koymak, mekanizmanın sağlayamayacağı tek olguyu uydurmak olurdu.
openCountInteger: Yalnızca bu kopyadaki sayılan açılmalar; mesaj toplamıyla aynı elemelere tabidir: makine istekleri düşürülür ve otuz saniye içindeki tekrarlar tek bir açılmaya indirgenir.
clickCountInteger: Yalnızca bu kopyadaki sayılan tıklamalar; kopya başına değil bağlantı başına tekilleştirilir.
firstOpenAtString or nil: Bu kopyada sayılan en erken açılma; hiç yokken nil.
lastOpenAtString or nil: Bu kopyada sayılan en son açılma; hiç yokken nil.
firstClickAtString or nil: Bu kopyada sayılan en erken tıklama; hiç yokken nil.
lastClickAtString or nil: Bu kopyada sayılan en son tıklama; hiç yokken nil.

links içindeki her kayıt

idString: Bağlantının kendi kimliği, `lnk_…`. Bir tıklama satırındaki `linkId` alanının belirttiği değer budur; böylece `list_clicks` içindeki bir erişim buradaki kayıtla eşleştirilebilir.
urlString: Bağlantının gerçekte gittiği yer; yeniden yazılmadan önce iletideki hâliyle. Yönlendirici bir kimliği buna çözümler ve ziyaretçiyi oraya gönderir.
labelString or nil: İletide göründüğü hâliyle bağlantı metni; bağlantının metni yoksa (örneğin bir görsel ya da çıplak bir URL) nil. Bir raporun üç izleme parametresi taşıyan bir URL'yi alıntılamak yerine “fiyatlandırma bağlantısı” diyebilmesi için vardır ve asla `url` yerine geçmez.
clickCountInteger: Bu bağlantıya yapılan sayılan ziyaretler, kopyalar üzerinden toplanır. Mesajdaki `clickCount` ile aynı, bağlantı başına otuz saniyelik pencere geçerlidir.
clickCountRawInteger: Bu bağlantıya yapılan her ziyaret; makine istekleri ve tekrarlar dahil.