PHP

ردیابی بازشدن و کلیک

`emails->getTracking` و کل فضای نام `tracking`.

یک پیام

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;}

پیامی که هرگز ردیابی نشده، به‌جای گزارشی خالی، یک NotFoundException را پرتاب می‌کند که isNotFound() آن true است. «چیزی ثبت نکردیم» و «کسی بازش نکرد» دو پاسخ متفاوت‌اند و نباید پاسخی مشترک داشته باشند. پیامی که با کلید test فرستاده شود هرگز ردیابی نمی‌شود، پس همیشه همین استثنا را پرتاب می‌کند.

در سراسر صندوق

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 و listClicks یک OpenEmail\Result\Page برمی‌گردانند، و listAll، iterate، listAllOpens، iterateOpens، listAllClicks و iterateClicks همهٔ صفحه‌ها را برایتان می‌پیمایند. get، listOpens و listClicks هم شناسهٔ ارسال msg_… را می‌گیرند و هم شناسهٔ خودِ رکورد ردیابی، tmsg_….

فضای نامی از آنِ خودش است نه چند متد روی emails، و دلیلش پوشش است: emails رکوردهای ارسال را فهرست می‌کند، که فقط برای نامه‌ای وجود دارند که همین API رسیدگی کرده باشد. کامپوزر، ابزارهای MCP و دستیار همه بدون آن می‌فرستند، پس گزارشی که روی emails ساخته شود گزارشی دربارهٔ ترافیک API شما می‌شد، نه دربارهٔ صندوق پستی.

خواندن صادقانهٔ اعداد

جفت	معنایش چیست
opens و clicks	آنچه اعمال شد: اینکه پیام با pixel یا با پیوندهای بازنویسی‌شده بیرون رفت یا نه.
opened و clicked	آنچه رخ داد.
openCount	بازدیدهای شمرده‌شده. اسکنرها و پروکسی‌های حریم خصوصی کنار گذاشته شده‌اند.
openCountRaw	همهٔ بازدیدها. نقل‌کردن این عدد به‌عنوان تعامل، همان راهی است که نرخ باز شدن از 100% بالاتر می‌رود.
attributable	اینکه آیا یک خوانده‌شدن اصلاً می‌تواند به گیرنده‌ای نام‌برده نسبت داده شود یا نه.

نرخ‌های tracking->getStats روی پیام‌های «ردیابی‌شده» محاسبه می‌شوند، هرگز روی همهٔ آنچه فرستاده شده. وگرنه صندوقی که از هر ده پیام یکی را ردیابی می‌کند چنان به نظر می‌رسید که انگار فروپاشیده است. openRate و clickRate درصدهایی‌اند که تا یک رقم اعشار گرد شده‌اند، مانند 42.5، نه کسرهایی میان 0 و 1.

پارامترها: tracking->list

openedbool: `true` پیام‌هایی را انتخاب می‌کند که دست‌کم یک open شمرده‌شده دارند، `false` پیام‌های ردیابی‌شده‌ای را که هیچ‌کدام را ندارند. هیچ‌کدام پیش‌فرض نیست، و `false` هرگز به معنای نامهٔ ردیابی‌نشده نیست، که اصلاً در این فهرست نمی‌آید.
clickedbool: همان فیلتر برای کلیک‌های شمرده‌شده، که مستقل از `opened` اعمال می‌شود. هر دو را می‌شود داد، و آنگاه پیام‌ها باید هر دو را برآورده کنند.
daysint: چند روز از اکنون به عقب نگاه شود، 1 تا 365 با پیش‌فرض 30، و بیرون از این بازه یک 422 است. پنجره بر اساس زمان ساخته شدن رکورد ردیابی اندازه گرفته می‌شود، و فقط رکوردهایی فهرست می‌شوند که ارسالشان واقعاً انجام شده است.
minutesint: به‌جای آن، پنجره برحسب دقیقه، از 1 تا 527040، که وقتی هر دو تنظیم شوند بر `days` مقدم است. پنجرهٔ کوتاه‌تر از یک روز به `grain` ریزتری نیاز دارد.
grainstring: `minute`، `hour` یا `day`، با پیش‌فرض `day`. فقط آغاز پنجره را به پایین گرد می‌کند، تا این فهرست با `getStats` که با همان دانه‌بندی خوانده شود هم‌خوان باشد، و در شکل پاسخ هیچ اثری ندارد.
limitint: تعداد گزارش در هر صفحه، 1 تا 200 با پیش‌فرض 50، تازه‌ترین اول. `nextCursor` صفحه را با همان فیلترها به‌عنوان `cursor:` پس بدهید تا صفحهٔ بعد بیاید، یا بگذارید `listAll` و `iterate` کل پنجره را بپیمایند.
cursorstring: `nextCursor` صفحهٔ قبل، یک شناسهٔ `tmsg_`.
apiKeystring: به‌جای کلید کلاینت با این کلید فهرست می‌گیرد.

پاسخ: گزارش ردیابی

emails->getTracking و tracking->get یک گزارش را به‌صورت یک آرایه با کلیدهای camelCase برمی‌گردانند، و tracking->list صفحه‌ای از آن‌ها را برمی‌گرداند.

objectstring: روی گزارشی که به‌خودی‌خود گرفته شود، از راه `tracking->get`، `tracking->list` یا `emails->getTracking`، همیشه `tracking`. همان گزارش وقتی به شکل `tracking` درون پیامی از `emails->get` تو در تو بیاید، این کلید را ندارد، چون آنجا بخشی از همان پیام است نه چیزی که جداگانه گرفته شده باشد.
idstring: شناسهٔ خودِ رکورد ردیابی، `tmsg_…`. `listOpens` و `listClicks` بر اساس همین کلید کار می‌کنند، و `msg_…`ی که به آن‌ها داده شود نخست به‌عنوان همین جست‌وجو می‌شود.
sendIdstring or null: ارسال `msg_…` که این رکورد با آن متناظر است، و هر جا رکورد ارسالی نوشته نشده باشد null. کامپوزر، `sendEmail` در MCP و دستیار، همگی بدون آن ارسال می‌کنند. ردیابی کل صندوق پستی را پوشش می‌دهد، نه فقط ترافیک API را.
threadIdstring or null: پس از ارسال پر می‌شود تا یک رابط خواندن بتواند دوباره پیام را پیدا کند، و هر جا درایور چیزی گزارش نکرده باشد null است. باربر نیست: رکوردی که این فیلدش null است هم شمرده می‌شود.
messageIdstring or null: همان Message-ID مطابق RFC 5322، نه شناسهٔ ما. این هم پس از ارسال پر می‌شود، و هر جا لایهٔ انتقال چیزی برای پر کردنش برنگردانده باشد null است.
subjectstring or null: موضوع، همان‌گونه که هنگام ارسال بوده. روی پیامی که بدون موضوع ثبت شده null است.
fromstring: آدرس فرستنده، که روی خودِ رکورد کپی می‌شود نه اینکه از ارسال join شود. گزارش‌ها مدت‌ها بعد خوانده می‌شوند و آدرسی که از آن زمان اصلاح یا حذف شده باشد در غیر این صورت تاریخ را بازنویسی می‌کرد.
sourcestring: کدام بخش آن را فرستاده: `composer`، `api`، `mcp`، `ai` یا `queue`. ممکن است بخشی ظاهر شود که این بسته هنوز نامش را نمی‌برد، پس با مقدار ناشناخته به‌عنوان اطلاعات رفتار کنید نه خطا.
sentAtstring or null: زمانی که پیام رفته است، به‌صورت یک لحظهٔ ISO 8601. روی رکوردی که ارسالش هرگز کامل نشده null است. `tracking->list` این‌ها را کنار می‌گذارد، `get` نه.
opensbool: اینکه آیا روی این پیام پیکسل اعمال شده است یا نه. این همان کاری است که انجام شده، نه آنچه تنظیم حساب اکنون می‌گوید.
clicksbool: اینکه آیا پیوندهای این پیام بازنویسی شدند یا نه. وقتی بدنه هیچ پیوندی نداشته false است، چون آنگاه چیزی تغییر نکرده و رکوردی که خلافش را ادعا کند با بایت‌ها جور درنمی‌آمد.
openedbool: اینکه آیا در میان نسخه‌ها هیچ open شمرده‌شده‌ای ثبت شده است یا نه. آن را در کنار `opens` بخوانید: نبودِ داده به‌دلیل جمع‌نشدنش، با نخواندنِ پیام از سوی هیچ‌کس، دو واقعیت متفاوت است.
clickedbool: اینکه آیا هیچ click شمرده‌شده‌ای ثبت شده است یا نه. شاهدی قوی‌تر از یک open است، چون تصویرها بسیار بیشتر از آنکه پیوندها دنبال‌نشده بمانند مسدود می‌شوند.
attributablebool: اینکه آیا هر خوانده‌شدنِ اینجا می‌تواند به گیرنده‌ای نام‌برده نسبت داده شود یا نه. همان لحظه که نسخه‌ای نسبت‌داده‌نشده فعالیت شمرده‌شده نشان دهد false می‌شود، که همان حالت چندگیرنده‌ای است که یک بدنه زیر یک توکن به کل فهرست می‌رود؛ پس پیش از نوشتن «باب این را باز نکرده است» آن را بررسی کنید.
openCountint: باز شدن‌هایی که گمان می‌رود کار یک آدم بوده‌اند، جمع‌زده روی نسخه‌ها. بازدیدهای ماشینی کنار گذاشته می‌شوند و تکرارها در سی ثانیه در یکی جمع می‌شوند، پس این همان عددی است که باید جلوی چشم خواننده گذاشت.
clickCountint: کلیک‌های شمرده‌شده، جمع‌زده روی نسخه‌ها. به ازای هر پیوند یکتاسازی می‌شود نه به ازای هر پیام، پس دو پیوند متفاوت که با چند ثانیه فاصله دنبال شوند دو کلیک‌اند.
openCountRawint: هر واکشی pixel، با احتساب اسکنرها و پراکسی‌های حریم خصوصی. `openCountRaw` منهای `openCount` نشان می‌دهد چند تا کنار گذاشته شده‌اند، واکشی‌های ماشینی و تکرارهای درون سی ثانیه روی هم، و تنها شاهد موجود بر این است که این پالایش اصلاً رخ داده.
clickCountRawint: هر بازدید از یک پیوند بازنویسی‌شده، با احتساب بازدیدهای ماشینی و تکرارها.
firstOpenAtstring or null: نخستین باز شدنِ شمرده‌شده در میان نسخه‌ها، و تا وقتی هیچ‌کدام نباشد null. بازدیدهای ماشینی هرگز آن را جابه‌جا نمی‌کنند.
lastOpenAtstring or null: تازه‌ترین باز شدنِ شمرده‌شده در میان نسخه‌ها، و تا وقتی هیچ‌کدام نباشد null.
firstClickAtstring or null: نخستین کلیکِ شمرده‌شده در میان نسخه‌ها، و تا وقتی هیچ‌کدام نباشد null.
lastClickAtstring or null: تازه‌ترین کلیکِ شمرده‌شده در میان نسخه‌ها، و تا وقتی هیچ‌کدام نباشد null.
recipientsarray: برای هر نسخهٔ ردیابی‌شده یک ورودی: در جایی که لایهٔ انتقال اجازه می‌دهد بایت‌ها برای هر فرد متفاوت باشد، به ازای هر گیرنده، و جایی که چنین نیست، یک ورودی مشترکِ واحد. ورودی مشترک حذف می‌شود مگر آنکه واقعاً چیزی روی آن ثبت شده باشد، پس یک ردیف دست‌نخوردهٔ «کسی» هرگز کنار نام‌های واقعی نمی‌نشیند.
linksarray: هر پیوندی که در این پیام بازنویسی شده است، به ترتیب جایی که در بدنه نشسته بود. جایی که پیوندی نبوده خالی است: پیامی که با `clicks` خاموش ارسال شده، یا پیامی که بدنه‌اش اصلاً پیوندی نداشته.

هر مدخل در recipients

emailstring or null: این نسخه به چه کسی رفته است، با حروف کوچک و همان‌گونه که هنگام ارسال بوده. دقیقاً وقتی null است که `attributed` برابر false باشد.
kindstring or null: `to`، `cc` یا `bcc`: نشانی روی کدام سرآیند آمده بود، تا گزارش همان‌طور خوانده شود که خودِ پیام خوانده می‌شد. روی نسخهٔ مشترک null است، چون به هیچ نشانی‌ای تعلق ندارد.
attributedbool: اینکه این ردیف فردی را نام می‌برد یا نه. پیش از `email` آن را بخوانید: مقدار false یعنی نسخهٔ مشترک، که به محض ثبت هر بازدیدی روی آن فهرست می‌شود، و نسبت دادن نامی به آن بازدید، حتی در پیامی با یک گیرندهٔ واحد، همان یک واقعیتی را از خود می‌سازد که این سازوکار نمی‌تواند تأمینش کند.
openCountint: باز شدن‌های شمرده‌شده تنها روی همین نسخه، با همان استثناهای مجموع پیام: بازدیدهای ماشینی کنار گذاشته می‌شوند و تکرارها در فاصلهٔ سی ثانیه در یکی ادغام می‌شوند.
clickCountint: کلیک‌های شمرده‌شده تنها روی همین نسخه، که به‌جای هر نسخه، به ازای هر پیوند یکتاسازی می‌شود.
firstOpenAtstring or null: نخستین باز شدنِ شمرده‌شده روی این نسخه، و تا وقتی هیچ‌کدام نباشد null.
lastOpenAtstring or null: تازه‌ترین باز شدنِ شمرده‌شده روی این نسخه، و تا وقتی هیچ‌کدام نباشد null.
firstClickAtstring or null: نخستین کلیکِ شمرده‌شده روی این نسخه، و تا وقتی هیچ‌کدام نباشد null.
lastClickAtstring or null: تازه‌ترین کلیکِ شمرده‌شده روی این نسخه، و تا وقتی هیچ‌کدام نباشد null.

هر مدخل در links

idstring: شناسهٔ خودِ پیوند، `lnk_…`. همان مقداری است که `linkId` در یک ردیف کلیک نام می‌برد، پس یک بازدید از `listClicks` را می‌توان به مدخل اینجا بازگرداند.
urlstring: مقصد واقعی پیوند، همان‌گونه که پیش از بازنویسی در پیام بوده است. بازهدایت‌کننده شناسه را به همین مقدار برمی‌گرداند و بازدیدکننده را روانه می‌کند.
labelstring or null: متن لنگر همان‌گونه که در پیام آمده بود، یا هر جا پیوند متنی نداشته null، مثل یک تصویر یا یک URL خام. برای این است که گزارش بتواند بگوید «پیوند صفحهٔ قیمت‌ها» به‌جای نقل یک URL با سه پارامتر ردیابی روی آن، و هرگز جانشین `url` نمی‌شود.
clickCountint: بازدیدهای شمرده‌شدهٔ این پیوند، جمع‌بسته روی همهٔ نسخه‌ها. همان پنجرهٔ سی‌ثانیه‌ای به‌ازای هر پیوند که برای `clickCount` روی پیام به کار می‌رود.
clickCountRawint: هر بازدید از این پیوند، شامل بازدیدهای ماشینی و تکرارها.