SDK
السرد والجلب
`emails.list` و`emails.listAll` و`emails.iterate` و`emails.get` و`emails.listEvents`.
emails.list
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
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 على كل الصفحات قبل أن يعيد مصفوفة واحدة، لذا أعطه مرشِّحًا ينتهي. والترقيم قائم على المفاتيح في الحالتين، فرسالة تصل في أثناء المرور لا يمكنها أن تجعل هذا يتخطى سجلًا كما كانت الإزاحة ستفعل.
emails.get و emails.listEvents
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` المجرد بأحرف صغيرة. ويُكتب السجل بعد تجريد أي اسم معروض، فعنوان بصيغة الأقواس الزاوية مثل `Acme <[email protected]>` لا يطابق شيئًا. وتُحوَّل قيمتك إلى أحرف صغيرة قبل المقارنة، والمقارنة مساواة لا مطابقة بادئة أو نطاق.
limitnumber- عدد السجلات في هذه الصفحة، من 1 إلى 100، والافتراضي 25. وأي قيمة خارج هذا المدى تُرفض بـ 422 بدل أن تُحصر داخله.
cursorstring- معرّف رسالة (`msg_…`) للترقيم انطلاقًا منه. قائم على المفاتيح لا على الإزاحة: إذ تعود السجلات أقدم تمامًا من `createdAt` الخاص بتلك الرسالة، فالرسائل التي تصل في أثناء الصفحة لا يمكنها أن تدفع سجلًا خلفك. ومعرّف لا يسمي أي رسالة في مساحة العمل هذه يعطي 400.
الاستجابة: Page<EmailResource>
itemsEmailResource[]- صفحة واحدة من الرسائل، الأحدث أولًا حسب `createdAt`، مستخرجة من مُغلَّف `data` الخاص بواجهة API. ولا تحمل سجلات القائمة أبدًا تفصيل `recipients` لكل عنوان. فذلك في `get`.
hasMoreboolean- ما إذا كانت هناك سجلات أخرى تطابق المرشِّح بعد هذه الصفحة. ويُجاب عن ذلك بجلب سجل واحد زيادة على `limit` بدل استعلام عدّ ثانٍ.
nextCursorstring | null- المعرّف الذي تمرّره مرة أخرى كـ `cursor`، وnull في الصفحة الأخيرة. ويتوقف `iterate` و`listAll` عندما يكون هذا null أو تكون `hasMore` خاطئة، لأن صفحة تدّعي وجود المزيد دون أن تسمي مؤشرًا كانت ستدور إلى ما لا نهاية.
items[].object'email'- دائمًا `'email'` في سجل من سجلات هذه القائمة.
items[].idstring- المعرّف الخاص بهذه الواجهة، `msg_…`. وهو ما تأخذه كل نقاط emails الأخرى، وما يسميه المؤشر.
items[].statusEmailStatus- أين الرسالة في دورة حياتها. و`partial` حالة قائمة بذاتها لا نكهة من نكهات الفشل: فبعض المستلمين لديهم الرسالة ولا يمكن سحبها منهم، ومن ثَم فإعادة المحاولة خطأ.
items[].modeApiKeyMode- `live` أو `test`، مأخوذة من المفتاح الذي أرسل. والإرسال في وضع الاختبار يُسجَّل هنا ولا يُبثّ أبدًا.
items[].fromstring- العنوان الذي أُذن بالإرسال تحته، مخزَّنًا مجردًا وبأحرف صغيرة، فالاسم المعروض المعطى في `from` يخرج على الشبكة لكنه لا يُحفظ هنا. وهو سلسلة نصية لا كائن لأن هذه هي الهوية التي أُذن بها: فعنوان خارج نطاق إرسال المفتاح، ليس على نطاق يملكه ولا مسمّى عليه، يُرفض بـ 403، ولا يُستبدل بصمت بعنوان يملكه.
items[].subjectstring | null- الموضوع كما هو مخزَّن. ويكون null على رسالة سُجّلت دون موضوع.
items[].messageIdstring | null- ترويسة Message-ID بحسب RFC 5322، لا معرّفنا نحن. يكون null إلى أن توجد رسالة MIME، وتعيد خدمة الإرسال كتابته عند الخروج، فأي ارتداد أو DSN لاحق يحمل معرّفًا مختلفًا ويُربط عبر `items[].id` بدلًا منه.
items[].threadIdstring | null- المحادثة التي تنتمي إليها هذه الرسالة، حيث أُعطيت واحدة أو أُسندت إليها. وnull فيما عدا ذلك.
items[].transportEmailTransport | (string & {}) | null- كيف خرجت البايتات. يكون null حتى الإرسال، ونوعه مفتوح فلا تكون وسيلة نقل لا تسمّيها SDK بعد تغييرًا كاسرًا: فالسجلات المخزَّنة قد تسمي وسائل لم تعد مستخدمة.
items[].attemptsnumber- كم محاولة إرسال جرت على الرسالة، و0 قبل الأولى.
items[].lastErrorstring | null- أحدث خطأ في الإرسال، مكتوب لإنسان. ويكون null ما دام لم يفشل شيء.
items[].scheduledAtstring | null- متى يُتوقع أن تنطلق الرسالة، كلحظة بصيغة ISO-8601. ولا يكون null إلا على إرسال فوري بلا نافذة إلغاء: فالنافذة تأخير قصير لا أكثر، ومن ثَم يملأ `cancellableForSeconds` هذا الحقل أيضًا، على سجل حالته `queued` لا `scheduled`.
items[].cancellableUntilstring | null- اللحظة التي يُتوقع أن تنطلق فيها الرسالة، وتحمل القيمة نفسها التي يحملها `scheduledAt` في أي إرسال مؤجَّل وnull في غير المؤجَّل. وهي طابع زمني للعرض لا الاختبار الذي يجريه الخادم: فـ `cancel` يفرّع على `status`، ولا يوقف رسالة إلا ما دامت `queued` أو `scheduled`.
items[].sentAtstring | null- متى انطلقت. يكون null حتى يكتمل الإرسال، ولهذا فإن `status` لا هذا الحقل هو ما تفرّع عليه.
items[].tagsRecord<string, string>- الوسوم المعطاة عند الإرسال، تُعاد كما هي ولا تُفسَّر أبدًا. وهي دائمًا كائن (`{}` حين لا تُضبط أي منها، ولا تكون null أبدًا)، وتُعاد فقط: فهذه النقطة ترشّح على `status` و`from`، فالوسم شيء تقرؤه من رسالة لا وسيلة للعثور على واحدة.
items[].sourceEmailSource- أي واجهة طلبت الإرسال: `composer` أو `api` أو `mcp` أو `ai` أو `queue`. و`api` هو هذا العميل.
items[].createdAtstring- متى كُتب سجل الإرسال، وهو قبل الإرسال الفعلي. وهذا هو الحقل الذي ترتّب عليه القائمة والحقل الذي يقارن عليه المؤشر.
items[].trackingEmailTrackingSummary- ملخص التفاعل، ولا يظهر إلا على سجل رسالته كانت متتبَّعة ويغيب فيما عدا ذلك. فالغياب هو الجواب عن سؤال «هل تُتبّعت هذه الرسالة»، حيث كانت `openCount: 0` ستُقرأ على أنها «لم يفتحها أحد».
items[].tracking.opensboolean- ما إذا كانت هذه الرسالة قد خرجت ببكسل. وهذا ما طُبّق على هذه الرسالة، لا ما يقوله إعداد الحساب الآن.
items[].tracking.clicksboolean- ما إذا كانت روابط هذه الرسالة قد أُعيدت كتابتها. وتكون خاطئة عندما لا يكون في الجسم روابط لإعادة كتابتها، إذ لم يتغير عندئذ شيء.
items[].tracking.openedboolean- ما إذا كان قد سُجّل أي فتح محسوب، مشتقة من `openCount > 0`.
items[].tracking.clickedboolean- ما إذا كان قد سُجّل أي نقر محسوب، مشتقة من `clickCount > 0`.
items[].tracking.openCountnumber- عمليات الفتح التي يُعتقد أن إنسانًا سبّبها، مجموعة على كل نسخة من الرسالة. وتُسجَّل الماسحات ووسطاء الخصوصية لكنها تُستثنى، والجلبات المتكررة خلال ثلاثين ثانية تُدمج في واحدة.
items[].tracking.clickCountnumber- النقرات المحسوبة، مجموعة على النسخ. وتُزال التكرارات لكل رابط لا لكل رسالة، لأن اتّباع رابطين بفارق ثوانٍ فعلان لا تكرار.
items[].tracking.firstOpenAtstring | null- أول فتح محسوب عبر النسخ، وnull ما دام لا يوجد أي منها. والزيارات الآلية لا تحرّكه أبدًا.
items[].translationEmailTranslationResource- لا يظهر أبدًا في سجل قائمة: فسجل الترجمة يعيش داخل الطلب المخزَّن، وهو ما لا تجلبه القائمة عمدًا. وغيابه هنا لا يقول شيئًا عما إذا كانت الرسالة قد تُرجمت. اسأل `get`.