SDK
Theo dõi lượt mở và lượt nhấp
`emails.getTracking` và toàn bộ tài nguyên `tracking`.
Một thông điệp
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)Một thông điệp chưa bao giờ được theo dõi sẽ ném ra một OpenEmailApiError với isNotFound là true, chứ không phải một báo cáo rỗng. "Chúng tôi không ghi nhận gì" và "không ai mở nó" là hai câu trả lời khác nhau và không được dùng chung một phản hồi.
Trên toàn hộp thư
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 và listClicks trả về các mảng thuần. get, listOpens và listClicks nhận hoặc id gửi dạng msg_…, hoặc chính tmsg_… của bản ghi theo dõi.
Là một tài nguyên riêng thay vì các trường trên emails, và lý do là độ bao phủ: emails liệt kê các bản ghi gửi, vốn chỉ tồn tại với thư mà API này đã xử lý. Trình soạn thảo, các công cụ MCP và trợ lý đều gửi mà không có bản ghi đó, nên một báo cáo dựng trên emails sẽ là báo cáo về lưu lượng API của bạn chứ không phải về hộp thư.
Đọc các con số một cách trung thực
| Cặp trường | Ý nghĩa |
|---|---|
| `opens` / `clicks` | Thứ đã được ÁP DỤNG: thông điệp có rời đi kèm pixel hoặc liên kết đã viết lại hay không. |
| `opened` / `clicked` | Điều đã thực sự xảy ra. |
| `openCount` | Số lượt được tính. Đã loại trừ trình quét và proxy bảo mật. |
| `openCountRaw` | Mọi lượt truy cập. Trích con số này như mức độ tương tác chính là cách khiến tỷ lệ mở vượt quá 100%. |
| `attributable` | Liệu một lượt đọc có thể quy được cho một người nhận cụ thể hay không. |
Các tỷ lệ từ tracking.getStats được tính trên các thông điệp ĐƯỢC THEO DÕI, không bao giờ trên toàn bộ thư đã gửi. Nếu không, một hộp thư chỉ theo dõi một trong mười thông điệp sẽ trông như thể đã sụp đổ.
Tham số: tracking.list
openedboolean- `true` chọn các thông điệp có ít nhất một lượt mở được tính, `false` chọn các thông điệp được theo dõi mà không có lượt nào. Không giá trị nào là mặc định, và `false` không bao giờ có nghĩa là thư không được theo dõi, vốn hoàn toàn không xuất hiện trong danh sách này.
clickedboolean- Cùng bộ lọc đó nhưng cho các lượt nhấp được tính, áp dụng độc lập với `opened`. Có thể truyền cả hai, và thông điệp phải thoả mãn cả hai.
daysnumber- Nhìn lại bao nhiêu ngày tính từ bây giờ, từ 1 đến 365 và mặc định là 30; ngoài khoảng đó là một 422. Cửa sổ được đo theo thời điểm bản ghi theo dõi được tạo, và chỉ những bản ghi có lần gửi thực sự đã đi mới được liệt kê.
limitnumber- Tối đa bấy nhiêu thông điệp, từ 1 đến 200 và mặc định là 50, mới nhất trước. Không có cursor: đây là một báo cáo trên một cửa sổ thời gian chứ không phải một dòng tin, nên nó bị giới hạn bởi `days` và `limit` và được đọc trọn vẹn.
Phản hồi: TrackingResource
object'tracking'- Luôn là `'tracking'` trên một báo cáo được lấy trực tiếp, qua `tracking.get`, `tracking.list` hoặc `emails.getTracking`. Cũng báo cáo đó khi lồng dưới dạng `email.tracking` trên một thông điệp đã truy xuất sẽ không có khoá này, vì ở đó nó là một phần của đối tượng ấy chứ không phải thứ được lấy riêng.
idstring- Id của chính bản ghi theo dõi, dạng `tmsg_…`. Đó là thứ mà các lời gọi theo từng lượt `listOpens` và `listClicks` dùng làm khoá; một `msg_…` truyền cho chúng sẽ được phân giải về id này trước.
sendIdstring | null- Lần gửi `msg_…` mà bản ghi này tương ứng, và là null khi không có bản ghi gửi nào được ghi. Trình soạn thảo, `sendEmail` của MCP và trợ lý đều gửi mà không có bản ghi đó. Theo dõi bao phủ cả hộp thư, không chỉ lưu lượng API.
threadIdstring | null- Được điền sau khi truyền đi để giao diện đọc thư có thể tìm lại thông điệp, và là null khi driver không báo về giá trị nào. Không phải thứ chịu tải: một bản ghi có giá trị này null vẫn được tính.
messageIdstring | null- Message-ID theo RFC 5322, không phải id của chúng tôi. Cũng được điền sau khi truyền đi, và là null khi phương thức truyền không trả về gì để điền vào.
subjectstring | null- Tiêu đề đúng như tại thời điểm gửi. Null trên một thông điệp được ghi lại mà không có tiêu đề.
fromstring- Địa chỉ gửi, được sao chép vào bản ghi chứ không join từ lần gửi. Báo cáo thường được đọc rất lâu sau đó, và một địa chỉ đã bị sửa hoặc gỡ bỏ kể từ đó sẽ viết lại lịch sử.
sourceEmailSource | (string & {})- Bề mặt nào đã gửi nó: `composer`, `api`, `mcp`, `ai` hoặc `queue`. Kiểu mở, nên một bề mặt mà SDK này chưa đặt tên không phải là một thay đổi phá vỡ.
sentAtstring | null- Thời điểm thông điệp được gửi đi, dưới dạng một mốc ISO-8601. Null trên một bản ghi mà lần gửi không bao giờ hoàn tất. `tracking.list` loại trừ những bản ghi đó, `get` thì không.
opensboolean- Một pixel có được ÁP DỤNG cho thông điệp này hay không. Đây là điều đã được làm, không phải điều mà thiết lập tài khoản nói ở hiện tại.
clicksboolean- Các liên kết của thông điệp này có được viết lại hay không. False khi phần thân không chứa liên kết nào, vì khi đó không có gì bị thay đổi và một bản ghi nói ngược lại sẽ không khớp được với các byte thực tế.
openedboolean- Có lượt mở được tính nào được ghi nhận trên các bản sao hay không. Hãy đọc nó cùng với `opens`: không có dữ liệu vì không thu thập gì là một sự thật khác với việc không ai đọc thông điệp.
clickedboolean- Có lượt nhấp được tính nào được ghi nhận hay không. Đây là bằng chứng mạnh hơn một lượt mở, vì hình ảnh bị chặn thường xuyên hơn nhiều so với việc liên kết không được nhấp.
attributableboolean- Liệu mọi lượt đọc ở đây có thể quy được cho một người nhận cụ thể hay không. Nó thành false ngay khi một bản sao không quy được có hoạt động được tính, tức là trường hợp nhiều người nhận, khi một phần thân đi tới cả danh sách dưới một token duy nhất; vậy nên hãy kiểm tra nó trước khi viết "Bob chưa mở thư này".
openCountnumber- Các lượt mở được cho là do một con người gây ra, cộng dồn trên các bản sao. Các lượt máy bị loại trừ và các lượt lặp trong vòng ba mươi giây được gộp thành một, nên đây là con số nên đặt trước mắt người đọc.
clickCountnumber- Các lượt nhấp được tính, cộng dồn trên các bản sao. Được khử trùng lặp theo từng liên kết chứ không theo từng thông điệp, nên hai liên kết khác nhau được nhấp cách nhau vài giây là hai lượt nhấp.
openCountRawnumber- Mọi lượt tải pixel, bao gồm cả trình quét và proxy bảo mật. `openCountRaw - openCount` chính là số lượt mà bộ phân loại đã gạt sang một bên, và là bằng chứng duy nhất cho thấy việc lọc đã thực sự diễn ra.
clickCountRawnumber- Mọi lượt truy cập vào một liên kết đã viết lại, bao gồm cả lượt máy và lượt lặp.
firstOpenAtstring | null- Lượt mở được tính sớm nhất trên các bản sao, và là null khi chưa có lượt nào. Các lượt máy không bao giờ làm nó thay đổi.
lastOpenAtstring | null- Lượt mở được tính gần nhất trên các bản sao, null khi chưa có lượt nào.
firstClickAtstring | null- Lượt nhấp được tính sớm nhất trên các bản sao, null khi chưa có lượt nào.
lastClickAtstring | null- Lượt nhấp được tính gần nhất trên các bản sao, null khi chưa có lượt nào.
recipientsTrackingRecipientResource[]- Một mục cho mỗi bản sao được theo dõi: theo từng người nhận ở nơi phương thức truyền cho phép các byte khác nhau theo từng người, và một mục chung duy nhất ở nơi không cho phép. Mục chung bị loại bỏ trừ khi thực sự có gì đó rơi vào nó, nên một hàng "ai đó" chưa hề được chạm tới sẽ không bao giờ nằm cạnh những cái tên thật.
recipients[].emailstring | null- Bản sao này đã đi tới ai, viết thường và đúng như tại thời điểm gửi. Null đúng khi `attributed` là false.
recipients[].kind'to' | 'cc' | 'bcc' | null- Địa chỉ xuất hiện trên header nào, để báo cáo đọc lên đúng như thông điệp thật. Null trên bản sao dùng chung, vốn không thuộc về địa chỉ nào.
recipients[].attributedboolean- Hàng này có nêu tên một người hay không. Hãy đọc nó trước `email`: false nghĩa là bản sao dùng chung, được liệt kê ngay khi có lượt truy cập nào rơi vào nó, và việc gán tên cho lượt truy cập đó, ngay cả trên một thông điệp chỉ có một người nhận, sẽ là bịa ra đúng cái sự thật mà cơ chế này không thể cung cấp.
recipients[].openCountnumber- Các lượt mở được tính chỉ riêng trên bản sao này, theo cùng các loại trừ như tổng của thông điệp: bỏ các lượt máy, và gộp các lượt lặp trong vòng ba mươi giây thành một.
recipients[].clickCountnumber- Các lượt nhấp được tính chỉ riêng trên bản sao này, khử trùng lặp theo từng liên kết chứ không theo từng bản sao.
recipients[].firstOpenAtstring | null- Lượt mở được tính sớm nhất trên bản sao này, null khi chưa có lượt nào.
recipients[].lastOpenAtstring | null- Lượt mở được tính gần nhất trên bản sao này, null khi chưa có lượt nào.
recipients[].firstClickAtstring | null- Lượt nhấp được tính sớm nhất trên bản sao này, null khi chưa có lượt nào.
recipients[].lastClickAtstring | null- Lượt nhấp được tính gần nhất trên bản sao này, null khi chưa có lượt nào.
linksTrackingLinkResource[]- Mọi liên kết đã được viết lại trong thông điệp này, sắp theo vị trí của chúng trong phần thân. Rỗng khi không có liên kết nào: một thông điệp gửi với `clicks` tắt, hoặc một thông điệp mà phần thân hoàn toàn không chứa liên kết.
links[].idstring- Id của chính liên kết, dạng `lnk_…`. Đó là giá trị mà `linkId` của một hàng nhấp trỏ tới, nên một lượt truy cập từ `listClicks` có thể được khớp ngược về mục ở đây.
links[].urlstring- Nơi liên kết thực sự dẫn tới, đúng như trong thông điệp trước khi viết lại. Bộ chuyển hướng phân giải một id về giá trị này rồi đưa khách truy cập đi tiếp.
links[].labelstring | null- Văn bản neo đúng như nó xuất hiện trong thông điệp, hoặc null khi liên kết không có, chẳng hạn một hình ảnh hay một URL trần. Nó ở đó để một báo cáo có thể nói "liên kết bảng giá" thay vì trích một URL kèm ba tham số theo dõi, và nó không bao giờ thay thế cho `url`.
links[].clickCountnumber- Các lượt truy cập được tính vào liên kết này, cộng dồn trên các bản sao. Cùng cửa sổ ba mươi giây theo từng liên kết như `clickCount` trên thông điệp.
links[].clickCountRawnumber- Mọi lượt truy cập vào liên kết này, bao gồm cả lượt máy và lượt lặp.