Python
السرد والجلب
`emails.list` و`emails.list_all` و`emails.iterate` و`emails.get` و`emails.list_events`.
emails.list
from openemail import openemail first = openemail.emails.list(status=['queued', 'scheduled'], from_='[email protected]', limit=50) if first['nextCursor']: second = openemail.emails.list( status=['queued', 'scheduled'], from_='[email protected]', limit=50, cursor=first['nextCursor'], )الصفحة هي {'items': [...], 'hasMore': ..., 'nextCursor': ...}. مرّر nextCursor مرة أخرى كـ cursor، مع المرشِّحات نفسها، للحصول على الصفحة التالية.
emails.iterate و emails.list_all
import sys from openemail import openemail for email in openemail.emails.iterate(status='failed'): print(email['id'], email['lastError'], file=sys.stderr) failures = openemail.emails.list_all(status='failed', from_='[email protected]')كلاهما يتبع nextCursor نيابةً عنك. وiterate مولِّد يجلب صفحة فقط عندما تصل الحلقة إليها، فالخروج من الحلقة يوقف الطلبات، بينما يمر list_all على كل الصفحات قبل أن يعيد قائمة واحدة، لذا أعطه مرشِّحًا ينتهي. والترقيم قائم على المفاتيح (keyset) في الحالتين، فرسالة تصل في أثناء المرور لا يمكنها أن تجعل هذا يتخطى سجلًا كما كانت الإزاحة ستفعل.
emails.get و emails.list_events
from openemail import openemail email = openemail.emails.get('msg_…')print(email['status'], email['recipients']) events = openemail.emails.list_all_events('msg_…')for event in events: print(event['type'], event['createdAt'])get هو الاستدعاء الوحيد الذي يعيد recipients، بسجل لكل عنوان. فقائمة من خمسين رسالة يحمل كل منها مستلميه صفحة تقرير لم يطلبها أحد.
المعاملات
statusEmailStatus | Sequence[EmailStatus]- حالة واحدة أو عدة حالات (`queued` أو `scheduled` أو `sending` أو `sent` أو `partial` أو `bounced` أو `cancelled` أو `failed`)، وتطابق أيًّا منها. وترسل SDK القائمة كقيمة واحدة مفصولة بفواصل لأن الخادم يقسّم على الفواصل؛ وأي قيمة خارج تلك المجموعة ترد 422 تسمي القيمة المجهولة.
broadcast_idstr- نسخ بث واحد فقط، وهو معرّف `brd_` من `broadcasts.send`. كل شخص يصل إليه البث يحصل على رسالة خاصة به، فهذا يعرض لمن ذهب وماذا حدث لكل نسخة. ويعرض `broadcasts.list_recipients` الأشخاص أنفسهم مع فتحاتهم ونقراتهم وإلغاءات اشتراكهم.
from_str- مطابقة تامة لعنوان الإرسال كما سُجّل، وهو `addr@host` المجرد بأحرف صغيرة. ويُكتب السجل بعد تجريد أي اسم معروض، فعنوان بصيغة الأقواس الزاوية مثل `Acme <[email protected]>` لا يطابق شيئًا. وتُحوَّل قيمتك إلى أحرف صغيرة قبل المقارنة، والمقارنة مساواة لا مطابقة بادئة أو نطاق. والشرطة السفلية في النهاية موجودة لأن `from` كلمة محجوزة في Python.
limitint- عدد السجلات في هذه الصفحة، من 1 إلى 100، والافتراضي 25. وأي قيمة خارج هذا المدى تُرفض بـ 422 بدل أن تُحصر داخله.
cursorstr- معرّف رسالة (`msg_…`) للترقيم انطلاقًا منه. قائم على المفاتيح لا على الإزاحة: إذ تعود السجلات أقدم تمامًا من `createdAt` الخاص بتلك الرسالة، فالرسائل التي تصل في أثناء الصفحة لا يمكنها أن تدفع سجلًا خلفك. ومعرّف لا يسمي أي رسالة في مساحة العمل هذه يعطي 400.
scheduled_fromdatetime | str- الرسائل المجدولة لهذه اللحظة أو بعدها فقط: `datetime`، أو لحظة بصيغة ISO-8601 مع منطقة زمنية. وتُستبعد الرسالة التي ليس لها `scheduledAt`، فمع `scheduled_to` و`status=['queued', 'scheduled']` يسرد هذا ما ينتظر الخروج ضمن نافذة زمنية.
scheduled_todatetime | str- الرسائل المجدولة لهذه اللحظة أو قبلها فقط. وقيمة `scheduled_from` أحدث منها تعطي 422 `invalid_parameter` على `scheduledTo`.
الاستجابة: Page[EmailResource]
itemslist[EmailResource]- صفحة واحدة من الرسائل، الأحدث أولًا حسب `createdAt`، مستخرجة من مُغلَّف `data` الخاص بواجهة API. ولا تحمل سجلات القائمة أبدًا تفصيل `recipients` لكل عنوان. فذلك في `get`.
hasMorebool- ما إذا كانت هناك سجلات أخرى تطابق المرشِّح بعد هذه الصفحة. ويُجاب عن ذلك بجلب سجل واحد زيادة على `limit` بدل استعلام عدّ ثانٍ.
nextCursorstr | None- المعرّف الذي تمرّره مرة أخرى كـ `cursor`، وnull في الصفحة الأخيرة. ويتوقف `iterate` و`list_all` عندما يكون هذا null أو تكون `hasMore` خاطئة، لأن صفحة تدّعي وجود المزيد دون أن تسمي مؤشرًا كانت ستدور إلى ما لا نهاية.
items[].objectLiteral['email']- دائمًا `'email'` في سجل من سجلات هذه القائمة.
items[].idstr- المعرّف الخاص بهذه الواجهة، `msg_…`. وهو ما تأخذه كل نقاط emails الأخرى، وما يسميه المؤشر.
items[].statusEmailStatus- أين الرسالة في دورة حياتها. و`partial` حالة قائمة بذاتها لا نكهة من نكهات الفشل: فبعض المستلمين لديهم الرسالة ولا يمكن سحبها منهم، ومن ثَم فإعادة المحاولة خطأ. و`bounced` تعني أن الرسالة ارتدّت عن كل مستلميها بعد خروجها، فلم تصل إلى أحد، وكل مستلم في `get` يذكر السبب.
items[].modeApiKeyMode- `live` أو `test`، مأخوذة من المفتاح الذي أرسل. والإرسال في وضع الاختبار يُسجَّل هنا ولا يُبثّ أبدًا.
items[].fromstr- العنوان الذي أُذن بالإرسال تحته، مخزَّنًا مجردًا وبأحرف صغيرة، فالاسم المعروض المعطى في `from` يخرج على الشبكة لكنه لا يُحفظ هنا. وهو سلسلة نصية عادية لا قاموس لأن هذه هي الهوية التي أُذن بها: فعنوان خارج نطاق إرسال المفتاح، ليس على نطاق يملكه ولا مسمّى عليه، يُرفض بـ 403، ولا يُستبدل بصمت بعنوان يملكه.
items[].subjectstr | None- الموضوع كما هو مخزَّن. ويكون null على رسالة سُجّلت دون موضوع.
items[].messageIdstr | None- ترويسة Message-ID بحسب RFC 5322، لا معرّفنا نحن. يكون null إلى أن توجد رسالة MIME، وتعيد خدمة الإرسال كتابته عند الخروج، فأي ارتداد أو DSN لاحق يحمل معرّفًا مختلفًا ويُربط عبر `items[].id` بدلًا منه.
items[].threadIdstr | None- المحادثة التي تنتمي إليها هذه الرسالة، حيث أُعطيت واحدة أو أُسندت إليها. وnull فيما عدا ذلك.
items[].transportEmailTransport | str | None- كيف خرجت البايتات. يكون null حتى الإرسال، ونوعه مفتوح فلا تكون وسيلة نقل لا تسمّيها SDK بعد تغييرًا كاسرًا: فالسجلات المخزَّنة قد تسمي وسائل لم تعد مستخدمة.
items[].attemptsint- كم محاولة إرسال جرت على الرسالة، و0 قبل الأولى.
items[].lastErrorstr | None- أحدث خطأ في الإرسال، مكتوب لإنسان. ويكون null ما دام لم يفشل شيء.
items[].scheduledAtstr | None- متى يُتوقع أن تنطلق الرسالة، كلحظة بصيغة ISO-8601. ولا يكون null إلا على إرسال فوري بلا نافذة إلغاء: فالنافذة تأخير قصير لا أكثر، ومن ثَم يملأ `cancellableForSeconds` هذا الحقل أيضًا، على سجل تكون فيه `status` بقيمة `queued` لا `scheduled`.
items[].cancellableUntilstr | None- اللحظة التي يُتوقع أن تنطلق فيها الرسالة، وتحمل القيمة نفسها التي يحملها `scheduledAt` في أي إرسال مؤجَّل وnull في غير المؤجَّل. وهي طابع زمني للعرض لا الاختبار الذي يجريه الخادم: فـ `cancel` يفرّع على `status`، ولا يوقف رسالة إلا ما دامت `queued` أو `scheduled`.
items[].sentAtstr | None- متى انطلقت. يكون null حتى يكتمل الإرسال، ولهذا فإن `status` لا هذا الحقل هو ما تفرّع عليه.
items[].tagsdict[str, str]- التسميات المعطاة عند الإرسال، تُعاد كما هي ولا تُفسَّر أبدًا. دائمًا قاموس (`{}` حين لا يُضبط شيء، ولا تكون null أبدًا)، وتُعاد فقط: هذا الاستدعاء يرشّح حسب `status` و`from_` و`broadcast_id` و`scheduled_from` و`scheduled_to`، فالوسم شيء يُقرأ من الرسالة لا طريقة للعثور عليها.
items[].broadcastIdstr | None- البث `brd_` الذي هذه الرسالة نسخة منه، أو null لرسالة أُرسلت وحدها.
items[].sourceEmailSource | str- أي واجهة طلبت الإرسال: `composer` أو `api` أو `mcp` أو `ai` أو `oauth` أو `form`. و`api` هو هذا العميل بمفتاح API، و`oauth` هو هذا العميل برمز وصول.
items[].createdAtstr- متى كُتب سجل الإرسال، وهو قبل الإرسال الفعلي. وهذا هو الحقل الذي ترتّب عليه القائمة والحقل الذي يقارن عليه المؤشر.
items[].trackingNotRequired[EmailTrackingSummary]- ملخص التفاعل، ولا يظهر إلا على سجل رسالته كانت متتبَّعة ويغيب فيما عدا ذلك. فالغياب هو الجواب عن سؤال «هل تُتبّعت هذه الرسالة»، حيث كانت `openCount: 0` ستُقرأ على أنها «لم يفتحها أحد».
items[].tracking.opensbool- ما إذا كانت هذه الرسالة قد خرجت ببكسل. وهذا ما طُبّق على هذه الرسالة، لا ما يقوله إعداد الحساب الآن.
items[].tracking.clicksbool- ما إذا كانت روابط هذه الرسالة قد أُعيدت كتابتها. وتكون خاطئة عندما لا يكون في الجسم روابط لإعادة كتابتها، إذ لم يتغير عندئذ شيء.
items[].tracking.openedbool- ما إذا كان قد سُجّل أي فتح محسوب، مشتقة من `openCount > 0`.
items[].tracking.clickedbool- ما إذا كان قد سُجّل أي نقر محسوب، مشتقة من `clickCount > 0`.
items[].tracking.openCountint- عمليات الفتح التي يُعتقد أن إنسانًا سبّبها، مجموعة على كل نسخة من الرسالة. وتُسجَّل الماسحات ووسطاء الخصوصية لكنها تُستثنى، والجلبات المتكررة خلال ثلاثين ثانية تُدمج في واحدة.
items[].tracking.clickCountint- النقرات المحسوبة، مجموعة على النسخ. وتُزال التكرارات لكل رابط لا لكل رسالة، لأن اتّباع رابطين بفارق ثوانٍ فعلان لا تكرار.
items[].tracking.firstOpenAtstr | None- أول فتح محسوب عبر النسخ، وnull ما دام لا يوجد أي منها. والزيارات الآلية لا تحرّكه أبدًا.
items[].translationNotRequired[EmailTranslationResource]- لا يظهر أبدًا في سجل قائمة: فسجل الترجمة يعيش داخل الطلب المخزَّن، وهو ما لا تجلبه القائمة عمدًا. وغيابه هنا لا يقول شيئًا عما إذا كانت الرسالة قد تُرجمت. اسأل `get`.