PHP

Açılma ve tıklama izleme

`emails->getTracking` ve `tracking` ad alanının tamamı.

Tek mesaj

tracking.php

$report = $client->emails->getTracking('msg_3f9a1c07d2b84e6a9c5b1f20'); echo $report['openCount'], ' opens from ', count($report['recipients']), ' recipients', PHP_EOL; foreach ($report['links'] as $link) {    echo $link['url'], ' ', $link['clickCount'], PHP_EOL;}

Hiç izlenmemiş bir ileti boş bir rapor değil, isNotFound() değeri true olan bir NotFoundException 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 istisnayı fırlatır.

Posta kutusu genelinde

tracking_report.php

$unopened = $client->tracking->list(opened: false, days: 7, limit: 100);$stats = $client->tracking->getStats(days: 30, offsetMinutes: intdiv((int) date('Z'), 60));$report = $client->tracking->get('msg_3f9a1c07d2b84e6a9c5b1f20');$opens = $client->tracking->listOpens('msg_3f9a1c07d2b84e6a9c5b1f20', includeMachine: true);$clicks = $client->tracking->listClicks('msg_3f9a1c07d2b84e6a9c5b1f20'); echo count($unopened), ' unopened, ', $stats['openRate'], '% opened', PHP_EOL;echo count($opens), ' opens and ', count($clicks), ' clicks on ', $report['id'], PHP_EOL;

list, listOpens ve listClicks bir OpenEmail\Result\Page döndürür; listAll, iterate, listAllOpens, iterateOpens, listAllClicks ve iterateClicks ise her sayfayı sizin için dolaşır. get, listOpens ve listClicks, 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->getStats 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

openedbool: `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.
clickedbool: 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.
daysint: Ş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.
minutesint: 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 `getStats` ile eşleşir ve yanıtta hiçbir şeyi biçimlendirmez.
limitint: Sayfa başına rapor; 1 ile 200 arası, varsayılanı 50, en yeniler önce. Sonraki sayfa için sayfanın `nextCursor` değerini aynı filtrelerle `cursor:` olarak geri geçirin ya da pencerenin tamamını `listAll` ve `iterate` dolaşsın.
cursorstring: Önceki sayfanın `nextCursor` değeri, bir `tmsg_` kimliği.
apiKeystring: İstemcinin anahtarı yerine bu anahtarla listeler.

Yanıt: izleme raporu

emails->getTracking ve tracking->get tek bir raporu camelCase anahtarlı bir dizi 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->getTracking` ü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_…`. `listOpens` ve `listClicks` bu kimliğe göre çalışır ve onlara verilen bir `msg_…` önce bu kimliğe çözümlenir.
sendIdstring or null: Bu raporun ilişkili olduğu `msg_…` gönderimi; gönderim kaydı yazılmamışsa null. 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 null: Okuma arayüzünün mesajı yeniden bulabilmesi için iletimden sonra doldurulur; sürücü hiçbir şey bildirmediyse null olur. Kritik değildir: bu alanı null olan bir kayıt yine de sayılır.
messageIdstring or null: RFC 5322 Message-ID; bizim id'miz değil. O da iletimden sonra doldurulur ve taşıma katmanı dolduracak bir şey döndürmediyse null olur.
subjectstring or null: Gönderim anındaki hâliyle konu. Konusuz kaydedilmiş bir iletide null.
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 paketin 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 null: İletinin gittiği an, ISO 8601 anı olarak. Gönderimi hiç tamamlanmamış bir kayıtta null. `tracking->list` bunları dışarıda bırakır, `get` bırakmaz.
opensbool: Bu mesaja bir pikselin UYGULANIP uygulanmadığı. Bu, hesap ayarının şu anda ne dediği değil, ne yapıldığıdır.
clicksbool: 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ı.
openedbool: 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.
clickedbool: 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.
attributablebool: 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.
openCountint: 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.
clickCountint: 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.
openCountRawint: 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.
clickCountRawint: Yeniden yazılmış bir bağlantıya yapılan her ziyaret; makine istekleri ve tekrarlar dahil.
firstOpenAtstring or null: Kopyalar arasındaki en erken sayılan açılma; hiç yoksa null. Makine istekleri bunu asla değiştirmez.
lastOpenAtstring or null: Kopyalar arasındaki en son sayılan açılma; hiç yoksa null.
firstClickAtstring or null: Kopyalar arasındaki en erken sayılan tıklama; hiç yoksa null.
lastClickAtstring or null: Kopyalar arasındaki en son sayılan tıklama; hiç yoksa null.
recipientsarray: İ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: 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 null: Bu kopyanın kime gittiği; küçük harfe çevrilmiş ve gönderim anındaki hâliyle. Tam olarak `attributed` false olduğunda null.
kindstring or null: `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 null.
attributedbool: 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.
openCountint: 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.
clickCountint: Yalnızca bu kopyadaki sayılan tıklamalar; kopya başına değil bağlantı başına tekilleştirilir.
firstOpenAtstring or null: Bu kopyadaki en erken sayılan açılma; hiç yoksa null.
lastOpenAtstring or null: Bu kopyadaki en son sayılan açılma; hiç yoksa null.
firstClickAtstring or null: Bu kopyadaki en erken sayılan tıklama; hiç yoksa null.
lastClickAtstring or null: Bu kopyadaki en son sayılan tıklama; hiç yoksa null.

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 `listClicks` 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 null: İ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) null. 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.
clickCountint: 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.
clickCountRawint: Bu bağlantıya yapılan her ziyaret; makine istekleri ve tekrarlar dahil.