Ruby

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

`emails.list`، `emails.list_all`، `emails.iterate`، `emails.get` و `emails.list_events`.

emails.list

list_emails.rb

filters = {status: ["queued", "scheduled"], from: "[email protected]"} first = client.emails.list(**filters, limit: 50)second = client.emails.list(**filters, limit: 50, cursor: first.next_cursor) if first.next_cursor p first.items.size, second&.items&.size

هر صفحه یک OpenEmail::Page با items، has_more? و next_cursor است. next_cursor را با همان فیلترها به‌عنوان cursor: پس بدهید تا صفحهٔ بعد از آن را بگیرید.

emails.iterate و emails.list_all

iterate_emails.rb

client.emails.iterate(status: "failed") do |email|  warn "#{email[:id]} #{email[:lastError]}"end failures = client.emails.list_all(status: "failed", from: "[email protected]")puts failures.size

هر دو next_cursor را به‌جای شما دنبال می‌کنند. iterate صفحه را فقط وقتی می‌گیرد که پیمایش به آن برسد، پس break در بلاک، یا first یا find روی Enumeratorی که بدون بلاک برمی‌گرداند، درخواست‌ها را متوقف می‌کند، در حالی که list_all پیش از برگرداندن یک Array همهٔ صفحه‌ها را می‌پیماید، پس فیلتری به آن بدهید که تمام شود. در هر دو حالت صفحه‌بندی keyset است، پس پیامی که وسط پیمایش برسد نمی‌تواند باعث شود ردیفی از قلم بیفتد، آن‌طور که با offset می‌افتاد.

emails.get و emails.list_events

get_email.rb

email = client.emails.get("msg_3f9a1c07d2b84e6a9c5b1f20")puts email[:status]p email[:recipients] events = client.emails.list_all_events("msg_3f9a1c07d2b84e6a9c5b1f20")events.each { |event| puts "#{event[:type]} #{event[:createdAt]}" }

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

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

پارامترها

statusString or Array<String>: یک وضعیت یا چند وضعیت (`queued`، `scheduled`، `sending`، `sent`، `partial`، `bounced`، `cancelled`، `failed`)، که با هرکدام از آن‌ها که داده شود مطابقت می‌کند. `bounced` یعنی پیام برای همهٔ گیرندگانش برگشت خورده، در حالی که پیامی که برای بعضی برگشت خورده و به بقیه رسیده `partial` است. gem یک Array را به‌صورت یک مقدار جداشده با کاما می‌فرستد چون سرور روی کاما جدا می‌کند، و مقداری بیرون از این مجموعه یک 422 است که مقدار ناشناخته را نام می‌برد.
broadcast_idString: فقط نسخه‌های یک ارسال گروهی، یک شناسهٔ `brd_` از `broadcasts.send`. هر کسی که ارسال گروهی به او برسد پیام خودش را می‌گیرد، پس این فهرست نشان می‌دهد برای چه کسانی رفته و چه بر سر هر نسخه آمده. `broadcasts.list_recipients` همین افراد را همراه با باز کردن‌ها، کلیک‌ها و لغو اشتراک‌هایشان فهرست می‌کند.
fromString: تطبیق دقیق روی نشانی فرستنده، همان‌طور که ثبت شده، یعنی `addr@host` خام و با حروف کوچک. ردیف با حذف هر نام نمایشی نوشته می‌شود، پس angle-addrی مانند `Acme <[email protected]>` با هیچ‌چیز مطابقت نمی‌کند. مقدار شما پیش از مقایسه به حروف کوچک تبدیل می‌شود، و مقایسه برابری است نه پیشوند یا تطبیق دامنه.
scheduled_fromTime, DateTime or String: فقط پیام‌هایی که برای این لحظه یا پس از آن زمان‌بندی شده‌اند. همراه با `scheduled_to:` و `status: ["scheduled", "queued"]` آنچه را در یک بازه منتظر رفتن است فهرست می‌کند، همان‌طور که تقویم برنامه انجام می‌دهد. پیامی که `scheduledAt` ندارد کنار گذاشته می‌شود. یک Time، یک DateTime یا یک لحظهٔ ISO 8601 همراه با offset آن بدهید: Date در Ruby به‌صورت تاریخ خالی فرستاده می‌شود، که این دو فیلتر ردش می‌کنند.
scheduled_toTime, DateTime or String: فقط پیام‌هایی که برای این لحظه یا پیش از آن زمان‌بندی شده‌اند. `scheduled_from:` پس از `scheduled_to:` یک 422 `invalid_parameter` است.
limitInteger: ردیف‌های این صفحه، 1 تا 100 با پیش‌فرض 25. مقداری بیرون از این بازه به‌جای محدود شدن، با 422 رد می‌شود. روی `list_all` و `iterate` اندازهٔ هر صفحه‌ای است که می‌گیرند.
cursorString: شناسهٔ یک پیام (`msg_…`) که صفحه‌بندی از آن آغاز شود. keyset است نه offset: ردیف‌ها اکیداً قدیمی‌تر از `createdAt` آن پیام برمی‌گردند، پس ارسال‌هایی که وسط صفحه می‌رسند نمی‌توانند ردیفی را از جلوی شما رد کنند. شناسه‌ای که در این فضای کاری هیچ پیامی را نام نبرد یک 400 `invalid_cursor` است.
api_keyString: به‌جای کلید کلاینت با این کلید فهرست می‌گیرد.

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

پاسخ: OpenEmail::Page

itemsArray<Hash>: یک صفحه از پیام‌ها، تازه‌ترین اول بر اساس `createdAt`، که از پاکت `data` مربوط به API بیرون کشیده شده است. ردیف‌های فهرست هرگز تفکیکِ به‌ازای‌نشانیِ `recipients` را حمل نمی‌کنند. آن روی `get` است.
has_more?Boolean: اینکه آیا فراتر از این صفحه ردیف‌های دیگری با فیلتر می‌خوانند یا نه. پاسخش با گرفتن یکی بیش از `limit` به دست می‌آید، نه با کوئری شمارش دوم.
next_cursorString or nil: شناسه‌ای که باید به‌عنوان `cursor:` پس بدهید، و روی آخرین صفحه nil است. `iterate` و `list_all` وقتی این nil باشد یا `has_more?` برابر false باشد می‌ایستند، چون صفحه‌ای که ادعای ادامه کند اما هیچ cursorی را نام نبرد تا ابد حلقه می‌زد.

هر مورد

objectString: روی یک ردیف از این فهرست همیشه `email`.
idString: شناسهٔ خودِ این API، `msg_…`. همان چیزی است که هر فراخوانی دیگر emails می‌گیرد، و همان چیزی که cursor نام می‌برد.
statusString: پیام کجای زندگی‌اش است. `partial` وضعیتی از آنِ خودش است نه گونه‌ای از failed: بعضی گیرندگان آن را دارند و نمی‌شود پس گرفت، پس تلاش دوباره اشتباه است. و `bounced` یعنی پیام پس از رفتن از همه‌ی گیرندگان برگشت خورد، پس دست هیچ‌کس نیست، و هر گیرنده در `get` دلیلش را می‌گوید.
modeString: `live` یا `test`، برگرفته از کلیدی که آن را فرستاده. ارسال در حالت test همین‌جا ثبت می‌شود و هرگز منتقل نمی‌شود.
fromString: نشانی‌ای که ارسال زیر آن مجاز شمرده شد، که خام و با حروف کوچک ذخیره می‌شود، پس نام نمایشی‌ای که روی `from` داده شده باشد باز هم روی سیم بیرون می‌رود اما اینجا نگه داشته نمی‌شود. یک String ساده است نه یک Hash، چون این همان هویتی است که مجاز شمرده شد: نشانی‌ای بیرون از اسکوپ ارسالِ یک کلید، که نه روی دامنه‌ای است که آن کلید دارد و نه روی آن نام برده شده، با یک 403 رد می‌شود و هرگز بی‌سروصدا با نشانی مجاز عوض نمی‌شود.
subjectString or nil: موضوع همان‌طور که ذخیره شده. روی پیامی که بدون موضوع ثبت شده nil است.
messageIdString or nil: همان Message-ID مربوط به RFC 5322، نه شناسهٔ ما. تا وقتی MIME وجود نداشته باشد nil است، و سرویس ارسال در مسیر خروج آن را بازنویسی می‌کند، پس bounce یا DSN بعدی شناسهٔ دیگری حمل می‌کند و به‌جای آن با `id` تطبیق داده می‌شود.
threadIdString or nil: رشته‌ای که این پیام به آن تعلق دارد، در جایی که داده یا تخصیص داده شده باشد. در غیر این صورت nil.
transportString or nil: بایت‌ها چگونه رفتند. تا پیش از ارسال nil است. رکوردهای ذخیره‌شده ممکن است هنوز لایه‌های انتقالی را نام ببرند که دیگر استفاده نمی‌شوند، پس با مقداری که نمی‌شناسید به‌عنوان اطلاعات رفتار کنید نه خطا.
attemptsInteger: پیام چند بار تلاش برای ارسال داشته است؛ پیش از نخستین تلاش 0.
lastErrorString or nil: تازه‌ترین خطای ارسال، نوشته‌شده برای آدم. تا وقتی چیزی شکست نخورده nil است.
scheduledAtString or nil: زمانی که پیام باید برود، به شکل یک لحظهٔ ISO 8601. فقط روی ارسال فوریِ بدون پنجرهٔ لغو nil است: پنجره چیزی جز تأخیری کوتاه نیست، پس `cancellableForSeconds` هم این را پر می‌کند، روی ردیفی که `status` آن `queued` است نه `scheduled`.
cancellableUntilString or nil: لحظه‌ای که پیام باید برود، که روی هر ارسال به‌تعویق‌افتاده همان مقدار `scheduledAt` را دارد و روی ارسالی که به تعویق نیفتاده nil است. این زمانی است برای نمایش، نه آزمونی که سرور انجام می‌دهد: `cancel` روی `status` شاخه می‌زند و پیام را فقط تا وقتی هنوز `queued` یا `scheduled` است متوقف می‌کند.
sentAtString or nil: زمانی که رفت. تا کامل شدن ارسال nil است، و به همین دلیل باید روی `status` شاخه بزنید نه روی این.
tagsHash: برچسب‌هایی که هنگام ارسال داده شده‌اند، همان‌طور بازگردانده می‌شوند و هرگز تفسیر نمی‌شوند. همیشه یک Hash، خالی وقتی چیزی تنظیم نشده و هرگز nil، و فقط بازگردانده می‌شوند: این فهرست بر اساس `status`، `from`، `broadcast_id` و بازهٔ زمان‌بندی فیلتر می‌کند، پس برچسب چیزی است که از روی پیام خوانده می‌شود، نه راهی برای یافتن آن.
broadcastIdString or nil: ارسال گروهیِ `brd_` که این پیام نسخه‌ای از آن است، یا nil برای پیامی که تنها فرستاده شده.
sourceString: کدام سطح درخواست ارسال را داده است: `composer`، `api`، `mcp`، `ai` یا `queue`. `api` همین کلاینت است.
createdAtString: زمانی که رکورد ارسال نوشته شد، که پیش از ارسال واقعی است. فهرست بر اساس همین فیلد مرتب می‌شود و cursor با همین فیلد مقایسه می‌شود.
trackingHash: خلاصهٔ تعامل، که فقط روی ردیفی حاضر است که پیامش ردیابی شده و در غیر این صورت غایب است. پاسخِ «آیا این ردیابی شد؟» همین غیاب است، جایی که `openCount` برابر 0 به معنای «کسی بازش نکرد» خوانده می‌شد.
translationHash: هرگز روی یک ردیف فهرست حاضر نیست: رکورد ترجمه در درخواست ذخیره‌شده زندگی می‌کند، که فهرست عمداً آن را نمی‌گیرد. غیابش اینجا هیچ نمی‌گوید که پیام ترجمه شده یا نه. از `get` بپرسید.

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

opensBoolean: اینکه آیا این پیام با یک pixel بیرون رفت یا نه. آنچه بر همین پیام اعمال شد، نه آنچه تنظیم حساب اکنون می‌گوید.
clicksBoolean: اینکه آیا پیوندهای این پیام بازنویسی شدند یا نه. وقتی بدنه هیچ پیوندی برای بازنویسی نداشته false است، چون آنگاه چیزی تغییر نکرده.
openedBoolean: اینکه آیا هیچ باز شدنِ شمرده‌شده‌ای ثبت شده است یا نه، که از بالاتر بودن `openCount` از 0 مشتق می‌شود.
clickedBoolean: اینکه آیا هیچ کلیکِ شمرده‌شده‌ای ثبت شده است یا نه، که از بالاتر بودن `clickCount` از 0 مشتق می‌شود.
openCountInteger: باز شدن‌هایی که گمان می‌رود کار یک آدم بوده‌اند، جمع‌زده روی هر نسخه از پیام. اسکنرها و پروکسی‌های حریم خصوصی ثبت می‌شوند اما کنار گذاشته می‌شوند، و واکشی‌های تکراری در سی ثانیه در یکی جمع می‌شوند.
clickCountInteger: کلیک‌های شمرده‌شده، جمع‌زده روی نسخه‌ها. به ازای هر پیوند یکتاسازی می‌شود نه به ازای هر پیام، چون دنبال‌کردن دو پیوند با چند ثانیه فاصله دو کنش است نه یک تکرار.
firstOpenAtString or nil: نخستین باز شدنِ شمرده‌شده در میان نسخه‌ها، و تا وقتی هیچ‌کدام نباشد nil. بازدیدهای ماشینی هرگز آن را جابه‌جا نمی‌کنند.