السرد والاسترجاع
ابحث عن الرسائل، واطّلع على مصير إحداها.
ينفّذ أيًّا من الاستدعاءات الـ3 في هذه الصفحة على مساحة عملك، بمفتاحك أنت.
السرد
GET /emails، الأحدث أولًا. رشِّح بـ status (مفصولة بفواصل) وfrom. والتصفّح بنظام keyset لا بالإزاحة: مرّر قيمة nextCursor التي أُعطيتها. فالتصفّح بالإزاحة يتخطى صفوفًا بصمت حين تصل رسائل جديدة أثناء تصفّحك.
{ "object": "list", "data": [ … ], "hasMore": true, "nextCursor": "msg_01j8…" }الصف الذي جرى تتبعه يحمل كذلك كائن tracking مختصرًا: opens وclicks وopened وclicked وopenCount وclickCount وfirstOpenAt. أما الصف الذي لم يُتتبَّع فلا يحمل مفتاح tracking إطلاقًا: فـ openCount: 0 على رسالة لم تحمل بكسلًا قط تُقرأ على أنها "لم يفتحها أحد"، وهو ادعاء لسنا في موضع يسمح لنا به.
استرجاع رسالة واحدة
GET /emails/{id} يعيد الرسالة مع حالة التسليم لكل مستلِم، ومع تقرير التتبع الكامل بدلًا من ملخص القائمة، لأن استرجاعًا واحدًا يحتمل التفصيل لكل مستلِم ويحتمل الروابط. والمعرّف غير الموجود هو 404، لا نجاح مفبرك.
| حالة المستلِم | المعنى |
|---|---|
| pending | لم تُرسَل بعد. |
| delivered | سُلّمت إلى ناقل البريد لهذا العنوان. |
| failed | رفضها ناقل البريد. |
| uncertain | أخفق ناقل البريد في منتصف الطريق ولا يستطيع تحديد المستلِمين الذين بلغهم. تُعرض كما هي بدل تخمينها في أي اتجاه. |
الأحداث
GET /emails/{id}/events يعيد الأثر، الأقدم أولًا: email.accepted وemail.queued وemail.scheduled وemail.sent وemail.failed وemail.cancelled وemail.rescheduled، وعلى رسالة متتبَّعة email.opened وemail.clicked وemail.downloaded حين تقع. ولتُبلَّغ بها بدل استطلاعها، سجّل webhook.