PHP

فهرست و دریافت

`emails->list`، `emails->listAll`، `emails->iterate`، `emails->get` و `emails->listEvents`.

emails->list

list_emails.php

$filters = ['status' => ['queued', 'scheduled'], 'from' => '[email protected]']; $first = $client->emails->list(...$filters, limit: 50);$second = $first->hasMore ? $client->emails->list(...$filters, limit: 50, cursor: $first->nextCursor) : null; echo count($first), ' ', $second === null ? 0 : count($second), PHP_EOL;

هر صفحه یک OpenEmail\Result\Page با items، hasMore و nextCursor است. nextCursor را با همان فیلترها به‌عنوان cursor: پس بدهید تا صفحهٔ بعد از آن را بگیرید. باز کردن یک آرایهٔ فیلتر در هر فراخوانی، همان‌طور که ...$filters می‌کند، فیلترها را یکسان نگه می‌دارد.

emails->iterate و emails->listAll

iterate_emails.php

foreach ($client->emails->iterate(status: 'failed') as $email) {    error_log($email['id'] . ' ' . ($email['lastError'] ?? ''));} $failures = $client->emails->listAll(status: 'failed', from: '[email protected]');echo count($failures), PHP_EOL;

هر دو nextCursor را به‌جای شما دنبال می‌کنند. iterate یک Generator برمی‌گرداند که صفحه را فقط وقتی می‌گیرد که پیمایش به آن برسد، پس یک break از foreach درخواست‌ها را متوقف می‌کند، در حالی که listAll پیش از برگرداندن یک آرایه همهٔ صفحه‌ها را می‌پیماید، پس فیلتری به آن بدهید که تمام شود. در هر دو حالت صفحه‌بندی keyset است، پس پیامی که وسط پیمایش برسد نمی‌تواند باعث شود ردیفی از قلم بیفتد، آن‌طور که با offset می‌افتاد.

emails->get و emails->listEvents

get_email.php

$email = $client->emails->get('msg_3f9a1c07d2b84e6a9c5b1f20');echo $email['status'], PHP_EOL;print_r($email['recipients']); $events = $client->emails->listAllEvents('msg_3f9a1c07d2b84e6a9c5b1f20'); foreach ($events as $event) {    echo $event['type'], ' ', $event['createdAt'], PHP_EOL;}

get تنها فراخوانی‌ای است که recipients را برمی‌گرداند، یک آرایه به ازای هر نشانی با status، error و deliveredAt خودش. فهرستی از پنجاه پیام که هرکدام گیرندگانش را حمل کند، صفحه‌ای از گزارشی است که کسی نخواسته.

listEvents ردِ رویدادهای یک ارسال را می‌خواند، قدیمی‌ترین در ابتدا: email.accepted، email.queued، email.sent، email.delivered، email.bounced، email.opened و بقیه، هرکدام با یک آرایه به نام data که شکلش به type آن بستگی دارد. listAllEvents و iterateEvents کل این رد را برایتان می‌پیمایند. وب‌هوک‌ها زیرمجموعه‌ای از همین رویدادها را در لحظهٔ رخ دادن تحویل می‌دهند، پس وقتی وب‌هوکی از دست رفته، اینجا را نگاه کنید.

پارامترها

statusstring or array: یک وضعیت یا چند وضعیت (`queued`، `scheduled`، `sending`، `sent`، `partial`، `bounced`، `cancelled`، `failed`)، که با هرکدام از آن‌ها که داده شود مطابقت می‌کند. `bounced` یعنی پیام برای همهٔ گیرندگانش برگشت خورده، در حالی که پیامی که برای بعضی برگشت خورده و به بقیه رسیده `partial` است. کلاینت یک آرایه را به‌صورت یک مقدار جداشده با کاما می‌فرستد چون سرور روی کاما جدا می‌کند، و مقداری بیرون از این مجموعه یک 422 است که مقدار ناشناخته را نام می‌برد.
broadcastIdstring: فقط نسخه‌های یک ارسال گروهی، یک شناسهٔ `brd_` از `broadcasts->send`. هر کسی که ارسال گروهی به او برسد پیام خودش را می‌گیرد، پس این فهرست نشان می‌دهد برای چه کسانی رفته و چه بر سر هر نسخه آمده. `broadcasts->listRecipients` همین افراد را همراه با باز کردن‌ها، کلیک‌ها و لغو اشتراک‌هایشان فهرست می‌کند.
fromstring: تطبیق دقیق روی نشانی فرستنده، همان‌طور که ثبت شده، یعنی `addr@host` خام و با حروف کوچک. ردیف با حذف هر نام نمایشی نوشته می‌شود، پس angle-addrی مانند `Acme <[email protected]>` با هیچ‌چیز مطابقت نمی‌کند. مقدار شما پیش از مقایسه به حروف کوچک تبدیل می‌شود، و مقایسه برابری است نه پیشوند یا تطبیق دامنه.
scheduledFromDateTimeInterface or string: فقط پیام‌هایی که برای این لحظه یا پس از آن زمان‌بندی شده‌اند. همراه با `scheduledTo:` و `status: ['scheduled', 'queued']` آنچه را در یک بازه منتظر رفتن است فهرست می‌کند، همان‌طور که تقویم برنامه انجام می‌دهد. پیامی که `scheduledAt` ندارد کنار گذاشته می‌شود. یک `DateTimeInterface`، که به‌صورت لحظه‌ای با UTC فرستاده می‌شود، یا یک لحظهٔ ISO 8601 همراه با offset آن بدهید: رشتهٔ تاریخی بدون ساعت را این دو فیلتر رد می‌کنند.
scheduledToDateTimeInterface or string: فقط پیام‌هایی که برای این لحظه یا پیش از آن زمان‌بندی شده‌اند. `scheduledFrom:` پس از `scheduledTo:` یک 422 `invalid_parameter` است.
limitint: ردیف‌های این صفحه، 1 تا 100 با پیش‌فرض 25. مقداری بیرون از این بازه به‌جای محدود شدن، با 422 رد می‌شود. روی `listAll` و `iterate` اندازهٔ هر صفحه‌ای است که می‌گیرند.
cursorstring: شناسهٔ یک پیام (`msg_…`) که صفحه‌بندی از آن آغاز شود. keyset است نه offset: ردیف‌ها اکیداً قدیمی‌تر از `createdAt` آن پیام برمی‌گردند، پس ارسال‌هایی که وسط صفحه می‌رسند نمی‌توانند ردیفی را از جلوی شما رد کنند. شناسه‌ای که در این فضای کاری هیچ پیامی را نام نبرد یک 400 `invalid_cursor` است.
apiKeystring: به‌جای کلید کلاینت با این کلید فهرست می‌گیرد.

کلیدی که به برخی نشانی‌ها محدود شده فقط پیام‌هایی را می‌خواند که از نشانی‌های تحت پوشش آن فرستاده شده‌اند، و صفحه پس از همین فیلتر بریده می‌شود، پس هر صفحه به‌جز آخرین همچنان limit ردیف دارد. from:ی که کلید پوشش نمی‌دهد به‌جای 403 یک صفحهٔ آخرِ خالی برمی‌گرداند.

پاسخ: OpenEmail\Result\Page

itemsarray: یک صفحه از پیام‌ها، تازه‌ترین اول بر اساس `createdAt`، که از پاکت `data` مربوط به API بیرون کشیده شده است. ردیف‌های فهرست هرگز تفکیکِ به‌ازای‌نشانیِ `recipients` را حمل نمی‌کنند. آن روی `get` است.
hasMorebool: اینکه آیا فراتر از این صفحه ردیف‌های دیگری با فیلتر می‌خوانند یا نه. پاسخش با گرفتن یکی بیش از `limit` به دست می‌آید، نه با کوئری شمارش دوم.
nextCursorstring or null: شناسه‌ای که باید به‌عنوان `cursor:` پس بدهید، و روی آخرین صفحه null است. `iterate` و `listAll` وقتی این null باشد یا `hasMore` برابر false باشد می‌ایستند، چون صفحه‌ای که ادعای ادامه کند اما هیچ cursorی را نام نبرد تا ابد حلقه می‌زد.

هر مورد

objectstring: روی یک ردیف از این فهرست همیشه `email`.
idstring: شناسهٔ خودِ این API، `msg_…`. همان چیزی است که هر فراخوانی دیگر emails می‌گیرد، و همان چیزی که cursor نام می‌برد.
statusstring: پیام کجای زندگی‌اش است. `partial` وضعیتی از آنِ خودش است نه گونه‌ای از failed: بعضی گیرندگان آن را دارند و نمی‌شود پس گرفت، پس تلاش دوباره اشتباه است. و `bounced` یعنی پیام پس از رفتن از همه‌ی گیرندگان برگشت خورد، پس دست هیچ‌کس نیست، و هر گیرنده در `get` دلیلش را می‌گوید.
modestring: `live` یا `test`، برگرفته از کلیدی که آن را فرستاده. ارسال در حالت test همین‌جا ثبت می‌شود و هرگز منتقل نمی‌شود.
fromstring: نشانی‌ای که ارسال زیر آن مجاز شمرده شد، که خام و با حروف کوچک ذخیره می‌شود، پس نام نمایشی‌ای که روی `from` داده شده باشد باز هم روی سیم بیرون می‌رود اما اینجا نگه داشته نمی‌شود. یک رشتهٔ ساده است نه یک آرایه، چون این همان هویتی است که مجاز شمرده شد: نشانی‌ای بیرون از اسکوپ ارسالِ یک کلید، که نه روی دامنه‌ای است که آن کلید دارد و نه روی آن نام برده شده، با یک 403 رد می‌شود و هرگز بی‌سروصدا با نشانی مجاز عوض نمی‌شود.
subjectstring or null: موضوع همان‌طور که ذخیره شده. روی پیامی که بدون موضوع ثبت شده null است.
messageIdstring or null: همان Message-ID مربوط به RFC 5322، نه شناسهٔ ما. تا وقتی MIME وجود نداشته باشد null است، و سرویس ارسال در مسیر خروج آن را بازنویسی می‌کند، پس bounce یا DSN بعدی شناسهٔ دیگری حمل می‌کند و به‌جای آن با `id` تطبیق داده می‌شود.
threadIdstring or null: رشته‌ای که این پیام به آن تعلق دارد، در جایی که داده یا تخصیص داده شده باشد. در غیر این صورت null.
transportstring or null: بایت‌ها چگونه رفتند. تا پیش از ارسال null است. رکوردهای ذخیره‌شده ممکن است هنوز لایه‌های انتقالی را نام ببرند که دیگر استفاده نمی‌شوند، پس با مقداری که نمی‌شناسید به‌عنوان اطلاعات رفتار کنید نه خطا.
attemptsint: پیام چند بار تلاش برای ارسال داشته است؛ پیش از نخستین تلاش 0.
lastErrorstring or null: تازه‌ترین خطای ارسال، نوشته‌شده برای آدم. تا وقتی چیزی شکست نخورده null است.
scheduledAtstring or null: زمانی که پیام باید برود، به شکل یک لحظهٔ ISO 8601. فقط روی ارسال فوریِ بدون پنجرهٔ لغو null است: پنجره چیزی جز تأخیری کوتاه نیست، پس `cancellableForSeconds` هم این را پر می‌کند، روی ردیفی که `status` آن `queued` است نه `scheduled`.
cancellableUntilstring or null: لحظه‌ای که پیام باید برود، که روی هر ارسال به‌تعویق‌افتاده همان مقدار `scheduledAt` را حمل می‌کند و روی ارسالی که به تعویق نیفتاده null است. این زمانی است برای نمایش، نه آزمونی که سرور انجام می‌دهد: `cancel` روی `status` شاخه می‌زند و پیام را فقط تا وقتی هنوز `queued` یا `scheduled` است متوقف می‌کند.
sentAtstring or null: زمانی که رفت. تا کامل شدن ارسال null است، و به همین دلیل باید روی `status` شاخه بزنید نه روی این.
tagsarray: برچسب‌هایی که هنگام ارسال داده شده‌اند، همان‌طور بازگردانده می‌شوند و هرگز تفسیر نمی‌شوند. همیشه یک آرایه، خالی وقتی چیزی تنظیم نشده و هرگز null، و فقط بازگردانده می‌شوند: این فهرست بر اساس `status`، `from`، `broadcastId` و بازهٔ زمان‌بندی فیلتر می‌کند، پس برچسب چیزی است که از روی پیام خوانده می‌شود، نه راهی برای یافتن آن.
broadcastIdstring or null: ارسال گروهیِ `brd_` که این پیام نسخه‌ای از آن است، یا null برای پیامی که تنها فرستاده شده.
sourcestring: کدام سطح درخواست ارسال را داده است: `composer`، `api`، `mcp`، `ai` یا `queue`. `api` همین کلاینت است.
createdAtstring: زمانی که رکورد ارسال نوشته شد، که پیش از ارسال واقعی است. فهرست بر اساس همین فیلد مرتب می‌شود و cursor با همین فیلد مقایسه می‌شود.
trackingarray: خلاصهٔ تعامل، که فقط روی ردیفی حاضر است که پیامش ردیابی شده و در غیر این صورت غایب است. پاسخِ «آیا این ردیابی شد؟» همین غیاب است، جایی که `openCount` برابر 0 به معنای «کسی بازش نکرد» خوانده می‌شد، پس به‌جای آنکه وجود کلید را فرض کنید، آن را با `?? null` بخوانید.
translationarray: هرگز روی یک ردیف فهرست حاضر نیست: رکورد ترجمه در درخواست ذخیره‌شده زندگی می‌کند، که فهرست عمداً آن را نمی‌گیرد. غیابش اینجا هیچ نمی‌گوید که پیام ترجمه شده یا نه. از `get` بپرسید.

ردیابی یک مورد

opensbool: اینکه آیا این پیام با یک pixel بیرون رفت یا نه. آنچه بر همین پیام اعمال شد، نه آنچه تنظیم حساب اکنون می‌گوید.
clicksbool: اینکه آیا پیوندهای این پیام بازنویسی شدند یا نه. وقتی بدنه هیچ پیوندی برای بازنویسی نداشته false است، چون آنگاه چیزی تغییر نکرده.
openedbool: اینکه آیا هیچ باز شدنِ شمرده‌شده‌ای ثبت شده است یا نه، که از بالاتر بودن `openCount` از 0 مشتق می‌شود.
clickedbool: اینکه آیا هیچ کلیکِ شمرده‌شده‌ای ثبت شده است یا نه، که از بالاتر بودن `clickCount` از 0 مشتق می‌شود.
openCountint: باز شدن‌هایی که گمان می‌رود کار یک آدم بوده‌اند، جمع‌زده روی هر نسخه از پیام. اسکنرها و پروکسی‌های حریم خصوصی ثبت می‌شوند اما کنار گذاشته می‌شوند، و واکشی‌های تکراری در سی ثانیه در یکی جمع می‌شوند.
clickCountint: کلیک‌های شمرده‌شده، جمع‌زده روی نسخه‌ها. به ازای هر پیوند یکتاسازی می‌شود نه به ازای هر پیام، چون دنبال‌کردن دو پیوند با چند ثانیه فاصله دو کنش است نه یک تکرار.
firstOpenAtstring or null: نخستین باز شدنِ شمرده‌شده در میان نسخه‌ها، و تا وقتی هیچ‌کدام نباشد null. بازدیدهای ماشینی هرگز آن را جابه‌جا نمی‌کنند.