SDK
Açılma ve tıklama izleme
`emails.getTracking` ve `tracking` kaynağının tamamı.
Tek mesaj
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)Hiç izlenmemiş bir mesaj, boş bir rapor değil, isNotFound değeri true olan bir OpenEmailApiError fırlatır. “Hiçbir şey kaydetmedik” ile “kimse açmadı” farklı yanıtlardır ve aynı yanıtı paylaşmamalıdır.
Posta kutusu genelinde
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 ve listClicks düz dizi döndürür. get, listOpens ve listClicks ya msg_… gönderim id'sini ya da izleme kaydının kendi tmsg_… id'sini alır.
emails üzerindeki alanlar yerine kendi başına bir kaynak 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 kurulmuş bir rapor, posta kutusunun değil API trafiğinizin raporu olurdu.
Sayıları dürüstçe okumak
| Çift | Ne anlama gelir |
|---|---|
| `opens` / `clicks` | UYGULANAN şey: mesajın bir pikselle veya yeniden yazılmış bağlantılarla gidip gitmediği. |
| `opened` / `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 şeye göre değil İZLENEN mesajlara göredir. Aksi hâlde on mesajdan birini izleyen bir posta kutusu çökmüş gibi görünürdü.
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.
daysnumber- Şimdiden geriye kaç gün bakılacağı, 1 ila 365, varsayılan 30; bu aralığın dışında 422 verir. Pencere, izleme kaydının oluşturulma zamanına göre ölçülür ve yalnızca gönderimi gerçekten gitmiş kayıtlar listelenir.
limitnumber- En fazla bu kadar mesaj, 1 ila 200, varsayılan 50, en yeniden eskiye. Cursor yoktur: bu bir akış değil, bir pencere üzerindeki rapordur; `days` ve `limit` ile sınırlanır ve bütün olarak okunur.
Yanıt: TrackingResource
object'tracking'- `tracking.get`, `tracking.list` veya `emails.getTracking` üzerinden kendi başına getirilen bir raporda her zaman `'tracking'`. Getirilen bir mesajın içinde `email.tracking` olarak yer alan aynı rapor bu anahtar olmadan gelir, çünkü orada ayrıca getirilen bir şey değil o nesnenin parçasıdır.
idstring- İzleme kaydının kendi id'si, `tmsg_…`. İstek başına çağrılar olan `listOpens` ve `listClicks` bu değere göre anahtarlanır; onlara verilen bir `msg_…` önce buna çözümlenir.
sendIdstring | null- Bunun karşılık geldiği `msg_…` gönderimi; hiç gönderim kaydı yazılmamışsa null. Yazma ekranı, MCP'nin `sendEmail` aracı ve asistan, kayıt yazmadan gönderim yapar. İzleme yalnızca API trafiğini değil posta kutusunu kapsar.
threadIdstring | 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 | 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 | null- Gönderim anındaki hâliyle konu. Konusuz kaydedilmiş bir mesajda 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ı.
sourceEmailSource | (string & {})- Hangi yüzeyin gönderdiği: `composer`, `api`, `mcp`, `ai` veya `queue`. Tipi açık bırakılmıştır; böylece bu SDK'nın henüz adlandırmadığı bir yüzey kırıcı bir değişiklik olmaz.
sentAtstring | null- Mesajın ne zaman gittiği, bir ISO-8601 anı olarak. Gönderimi hiç tamamlanmamış bir kayıtta null. `tracking.list` bunları hariç tutar, `get` tutmaz.
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 mesajın bağlantılarının yeniden yazılıp yazılmadığı. Gövde hiç bağlantı taşımıyorsa false olur, çünkü o zaman hiçbir şey değiştirilmemiş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.
openCountnumber- 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.
clickCountnumber- 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.
openCountRawnumber- Her piksel isteği; tarayıcı botları ve gizlilik vekilleri dahil. `openCountRaw - openCount`, sınıflandırıcının kaç tanesini ayırdığını gösterir ve filtrelemenin yapıldığına dair elinizdeki tek kanıttır.
clickCountRawnumber- Yeniden yazılmış bir bağlantıya yapılan her ziyaret; makine istekleri ve tekrarlar dahil.
firstOpenAtstring | null- Kopyalar arasındaki en erken sayılan açılma; hiç yoksa null. Makine istekleri bunu asla değiştirmez.
lastOpenAtstring | null- Kopyalar arasındaki en son sayılan açılma; hiç yoksa null.
firstClickAtstring | null- Kopyalar arasındaki en erken sayılan tıklama; hiç yoksa null.
lastClickAtstring | null- Kopyalar arasındaki en son sayılan tıklama; hiç yoksa null.
recipientsTrackingRecipientResource[]- İ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.
recipients[].emailstring | null- Bu kopyanın kime gittiği; gönderim anındaki hâliyle ve küçük harfli. Tam olarak `attributed` false olduğunda null'dır.
recipients[].kind'to' | 'cc' | 'bcc' | null- Adresin hangi başlıkta göründüğü; böylece rapor, mesajın okunduğu gibi okunur. Hiçbir adrese ait olmayan paylaşılan kopyada null.
recipients[].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.
recipients[].openCountnumber- 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.
recipients[].clickCountnumber- Yalnızca bu kopyadaki sayılan tıklamalar; kopya başına değil bağlantı başına tekilleştirilir.
recipients[].firstOpenAtstring | null- Bu kopyadaki en erken sayılan açılma; hiç yoksa null.
recipients[].lastOpenAtstring | null- Bu kopyadaki en son sayılan açılma; hiç yoksa null.
recipients[].firstClickAtstring | null- Bu kopyadaki en erken sayılan tıklama; hiç yoksa null.
recipients[].lastClickAtstring | null- Bu kopyadaki en son sayılan tıklama; hiç yoksa null.
linksTrackingLinkResource[]- 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.
links[].idstring- Bağlantının kendi id'si, `lnk_…`. Bir tıklama satırındaki `linkId` alanının gösterdiği değer budur; böylece `listClicks` çağrısından gelen bir istek buradaki kayıtla eşleştirilebilir.
links[].urlstring- Bağlantının gerçekte nereye gittiği; mesajda yeniden yazılmadan önceki hâliyle. Yönlendirici bir id'yi buna geri çözümler ve ziyaretçiyi yoluna gönderir.
links[].labelstring | null- Bağlantı metninin mesajda göründüğü hâli ya da bağlantının metni yoksa (bir görsel veya çıplak bir URL gibi) 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` alanının yerini tutmaz.
links[].clickCountnumber- 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.
links[].clickCountRawnumber- Bu bağlantıya yapılan her ziyaret; makine istekleri ve tekrarlar dahil.