SDK

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

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

emails.list

list-emails.ts

const first = await openemail.emails.list({  status: ['queued', 'scheduled'],  from: '[email protected]',  limit: 50,}) const second = first.nextCursor  ? await openemail.emails.list({ status: ['queued', 'scheduled'], limit: 50, cursor: first.nextCursor })  : null

هر صفحه { items, hasMore, nextCursor } است. nextCursor را با همان فیلترها به‌عنوان cursor پس بدهید تا صفحهٔ بعد از آن را بگیرید.

emails.iterate و emails.listAll

iterate-emails.ts

for await (const email of openemail.emails.iterate({ status: 'failed' })) {  console.error(email.id, email.lastError)} const failures = await openemail.emails.listAll({ status: 'failed', from: '[email protected]' })

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

emails.get و emails.listEvents

get-email.ts

const email = await openemail.emails.get('msg_…')console.log(email.status, email.recipients) const events = await openemail.emails.listEvents('msg_…')for (const event of events) console.log(event.type, event.createdAt)

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

پارامترها

statusEmailStatus | EmailStatus[]: یک وضعیت یا چند وضعیت (`queued`، `scheduled`، `sending`، `sent`، `partial`، `cancelled`، `failed`)، که با هرکدام از آن‌ها که داده شود مطابقت می‌کند. SDK آرایه را به‌صورت یک مقدار واحدِ جداشده با کاما می‌فرستد چون سرور روی کاما می‌شکند؛ مقداری بیرون از آن مجموعه یک 422 است که مقدار ناشناخته را نام می‌برد.
fromstring: تطبیق دقیق روی نشانی فرستنده، همان‌طور که ثبت شده، یعنی `addr@host` خام و با حروف کوچک. ردیف با حذف هر نام نمایشی نوشته می‌شود، پس angle-addr ای مانند `Acme <[email protected]>` با هیچ‌چیز مطابقت نمی‌کند. مقدار شما پیش از مقایسه به حروف کوچک تبدیل می‌شود، و مقایسه برابری است نه پیشوند یا تطبیق دامنه.
limitnumber: ردیف‌های این صفحه، 1 تا 100 با پیش‌فرض 25. مقداری بیرون از این بازه به‌جای محدود شدن، با 422 رد می‌شود.
cursorstring: شناسهٔ یک پیام (`msg_…`) که صفحه‌بندی از آن آغاز شود. keyset است نه offset: ردیف‌ها اکیداً قدیمی‌تر از `createdAt` آن پیام برمی‌گردند، پس ارسال‌هایی که وسط صفحه می‌رسند نمی‌توانند ردیفی را از جلوی شما رد کنند. شناسه‌ای که در این workspace هیچ پیامی را نام نبرد یک 400 است.

پاسخ: Page<EmailResource>

itemsEmailResource[]: یک صفحه از پیام‌ها، تازه‌ترین اول بر اساس `createdAt`، که از پاکت `data` مربوط به API بیرون کشیده شده است. ردیف‌های فهرست هرگز تفکیکِ به‌ازای‌نشانیِ `recipients` را حمل نمی‌کنند. آن روی `get` است.
hasMoreboolean: اینکه آیا فراتر از این صفحه ردیف‌های دیگری با فیلتر می‌خوانند یا نه. پاسخش با گرفتن یکی بیش از `limit` به دست می‌آید، نه با کوئری شمارش دوم.
nextCursorstring | null: شناسه‌ای که باید به‌عنوان `cursor` پس بدهید، و روی آخرین صفحه null است. `iterate` و `listAll` وقتی این null باشد یا `hasMore` برابر false باشد می‌ایستند، چون صفحه‌ای که ادعای ادامه کند اما هیچ cursor ای را نام نبرد تا ابد حلقه می‌زد.
items[].object'email': روی یک ردیف از این فهرست همیشه `'email'`.
items[].idstring: شناسهٔ خودِ این API، `msg_…`. همان چیزی است که هر endpoint دیگر emails می‌گیرد، و همان چیزی که cursor نام می‌برد.
items[].statusEmailStatus: پیام کجای زندگی‌اش است. `partial` وضعیتی از آنِ خودش است نه گونه‌ای از failed: بعضی گیرندگان آن را دارند و نمی‌شود پس گرفت، پس تلاش دوباره اشتباه است.
items[].modeApiKeyMode: `live` یا `test`، برگرفته از کلیدی که آن را فرستاده. ارسال در حالت test همین‌جا ثبت می‌شود و هرگز منتقل نمی‌شود.
items[].fromstring: نشانی‌ای که ارسال زیر آن مجاز شمرده شد، که خام و با حروف کوچک ذخیره می‌شود، پس نام نمایشی‌ای که روی `from` داده شده باشد باز هم روی سیم بیرون می‌رود اما اینجا نگه داشته نمی‌شود. یک رشتهٔ ساده است نه یک object، چون این همان هویتی است که مجاز شمرده شد: نشانی‌ای بیرون از scope ارسالِ یک کلید، که نه روی دامنه‌ای است که آن کلید دارد و نه روی آن نام برده شده، با یک 403 رد می‌شود و هرگز بی‌سروصدا با نشانی مجاز عوض نمی‌شود.
items[].subjectstring | null: موضوع همان‌طور که ذخیره شده. روی پیامی که بدون موضوع ثبت شده null است.
items[].messageIdstring | null: همان Message-ID مربوط به RFC 5322، نه شناسهٔ ما. تا وقتی MIME وجود نداشته باشد null است، و سرویس ارسال در مسیر خروج آن را بازنویسی می‌کند، پس bounce یا DSN بعدی شناسهٔ دیگری حمل می‌کند و به‌جای آن روی `items[].id` همبسته می‌شود.
items[].threadIdstring | null: thread ای که این پیام به آن تعلق دارد، در جایی که یکی داده یا تخصیص داده شده باشد. در غیر این صورت null.
items[].transportEmailTransport | (string & {}) | null: بایت‌ها چگونه رفتند. تا پیش از ارسال null است، و نوعش باز گذاشته شده تا حمل‌ونقلی که این SDK هنوز نامش را نمی‌برد تغییری شکننده نباشد: رکوردهای ذخیره‌شده می‌توانند هنوز حمل‌ونقل‌هایی را نام ببرند که دیگر به کار نمی‌روند.
items[].attemptsnumber: پیام چند بار تلاش برای ارسال داشته است؛ پیش از نخستین تلاش 0.
items[].lastErrorstring | null: تازه‌ترین خطای ارسال، نوشته‌شده برای آدم. تا وقتی چیزی شکست نخورده null است.
items[].scheduledAtstring | null: زمانی که پیام باید برود، به شکل یک لحظهٔ ISO-8601. فقط روی ارسال فوریِ بدون پنجرهٔ لغو null است: پنجره چیزی جز تأخیری کوتاه نیست، پس `cancellableForSeconds` هم این را پر می‌کند، روی ردیفی که `status` آن `queued` است نه `scheduled`.
items[].cancellableUntilstring | null: لحظه‌ای که پیام باید برود، که روی هر ارسال به‌تعویق‌افتاده همان مقدار `scheduledAt` را حمل می‌کند و روی ارسالی که به تعویق نیفتاده null است. این زمانی است برای نمایش، نه آزمونی که سرور انجام می‌دهد: `cancel` روی `status` شاخه می‌زند و پیام را فقط تا وقتی هنوز `queued` یا `scheduled` است متوقف می‌کند.
items[].sentAtstring | null: زمانی که رفت. تا کامل‌شدن ارسال null است، و به همین دلیل باید روی `status` شاخه بزنید نه روی این.
items[].tagsRecord<string, string>: برچسب‌های داده‌شده هنگام ارسال، که بازتاب داده می‌شوند و هرگز تفسیر نمی‌شوند. همیشه یک object است (`{}` وقتی هیچ‌کدام تنظیم نشده باشد، هرگز null)، و فقط بازتاب است: این endpoint روی `status` و `from` فیلتر می‌کند، پس برچسب چیزی است که از روی یک پیام بخوانید، نه راهی برای یافتن آن.
items[].sourceEmailSource: کدام سطح درخواست ارسال را داده است: `composer`، `api`، `mcp`، `ai` یا `queue`. `api` همین کلاینت است.
items[].createdAtstring: زمانی که رکورد ارسال نوشته شد، که پیش از ارسال واقعی است. فهرست بر اساس همین فیلد مرتب می‌شود و cursor با همین فیلد مقایسه می‌شود.
items[].trackingEmailTrackingSummary: خلاصهٔ تعامل، که فقط روی ردیفی حاضر است که پیامش ردیابی شده و در غیر این صورت غایب است. پاسخِ «آیا این ردیابی شد؟» همین غیاب است، جایی که `openCount: 0` به معنای «کسی بازش نکرد» خوانده می‌شد.
items[].tracking.opensboolean: اینکه آیا این پیام با یک pixel بیرون رفت یا نه. آنچه بر همین پیام اعمال شد، نه آنچه تنظیم حساب اکنون می‌گوید.
items[].tracking.clicksboolean: اینکه آیا پیوندهای این پیام بازنویسی شدند یا نه. وقتی بدنه هیچ پیوندی برای بازنویسی نداشته false است، چون آنگاه چیزی تغییر نکرده.
items[].tracking.openedboolean: اینکه آیا هیچ open شمرده‌شده‌ای ثبت شده است یا نه، که از `openCount > 0` مشتق می‌شود.
items[].tracking.clickedboolean: اینکه آیا هیچ click شمرده‌شده‌ای ثبت شده است یا نه، که از `clickCount > 0` مشتق می‌شود.
items[].tracking.openCountnumber: باز شدن‌هایی که گمان می‌رود کار یک آدم بوده‌اند، جمع‌زده روی هر نسخه از پیام. اسکنرها و پروکسی‌های حریم خصوصی ثبت می‌شوند اما کنار گذاشته می‌شوند، و واکشی‌های تکراری در سی ثانیه در یکی جمع می‌شوند.
items[].tracking.clickCountnumber: کلیک‌های شمرده‌شده، جمع‌زده روی نسخه‌ها. به ازای هر پیوند یکتاسازی می‌شود نه به ازای هر پیام، چون دنبال‌کردن دو پیوند با چند ثانیه فاصله دو کنش است نه یک تکرار.
items[].tracking.firstOpenAtstring | null: نخستین باز شدنِ شمرده‌شده در میان نسخه‌ها، و تا وقتی هیچ‌کدام نباشد null. بازدیدهای ماشینی هرگز آن را جابه‌جا نمی‌کنند.
items[].translationEmailTranslationResource: هرگز روی یک ردیف فهرست حاضر نیست: رکورد ترجمه در درخواست ذخیره‌شده زندگی می‌کند، که فهرست عمداً آن را نمی‌گیرد. غیابش اینجا هیچ نمی‌گوید که پیام ترجمه شده یا نه. از `get` بپرسید.