SDK
الجدولة والإلغاء
`scheduledAt` و`emails.reschedule` و`emails.cancel`.
الإرسال لاحقًا
await openemail.emails.send({ ...message, scheduledAt: 'PT1H' })await openemail.emails.send({ ...message, scheduledAt: new Date('2027-01-01T09:00:00Z') })await openemail.emails.send({ ...message, scheduledAt: '2027-01-01T09:00:00.000Z' })كائن Date أو لحظة بصيغة ISO-8601 أو مدة مثل PT1H / P2D. حتى سنة من الآن، ولا تكون في الماضي أبدًا.
النقل والإيقاف
const queued = await openemail.emails.send({ ...message, scheduledAt: 'PT1H' }) await openemail.emails.reschedule(queued.id, new Date(Date.now() + 86_400_000))await openemail.emails.cancel(queued.id)لا يمكن إيقاف سوى الرسائل في الحالتين queued وscheduled؛ وأي شيء تجاوز ذلك يعطي conflict_error، لأن جزءًا منه صار في صندوق بريد أحدهم بالفعل. وإلغاء رسالة أُلغيت من قبل ينجح ولا يغيّر شيئًا.
نافذة تراجع بدلًا من ذلك
await openemail.emails.send({ ...message, cancellableForSeconds: 30 })الرسالة المجدولة قابلة للإلغاء أصلًا حتى تنطلق، فلا يمكن الجمع بين الاثنين، والخادم يرفض ذلك. استخدم هذا الخيار لنافذة تراجع عن الإرسال في رسالة فورية.
المعاملات: الجدولة
scheduledAtDate | string- متى تُرسل الرسالة، في `emails.send`: كائن `Date` أو لحظة بصيغة ISO-8601 أو مدة مثل `PT1H` أو `P2D`، ويحوّلها العميل إلى سلسلة للإرسال. على الأقل بعد ثانية من الآن وبحد أقصى 365 يومًا، وكلا الحدين يعطي `validation_error` على `scheduledAt`، واللغة الطبيعية غير مقبولة، لأن تحليل «الثلاثاء القادم» تحليلًا خاطئًا يرسل رسالة في وقت لا يمكن التراجع عنه.
cancellableForSecondsnumber- نافذة تراجع عن الإرسال على رسالة فورية: عدد صحيح من 0 إلى 900، والافتراضي 0. وأي قيمة فوق 0 تُرفض مع `scheduledAt`، التي تكون قابلة للإلغاء أصلًا حتى تنطلق، والرسالة المحتجزة بهذه الطريقة تبقى عند `queued` لا `scheduled`. فهي آلية التأجيل نفسها بتأخير قصير.
idstringمطلوب- المعرّف `msg_…`، وهو الوسيط الأول لكل من `emails.cancel` و`emails.reschedule`. وكلاهما يحتاج `emails:send` لا صلاحية خاصة به، وكلاهما يُحلّ داخل مساحة عمل المفتاح نفسها، فمعرّف يخص مساحة أخرى يعطي `not_found_error` تمامًا كمعرّف لم يوجد قط.
reschedule.scheduledAtDate | stringمطلوب- الوقت الجديد، كوسيط ثانٍ لـ `emails.reschedule`، يُحلَّل بالقواعد نفسها وفي نافذة السنة نفسها، وهو الشيء الوحيد الذي سيغيّره `PATCH /emails/{id}` الكامن خلفه. والمدة نسبية إلى لحظة قراءة الخادم لها، فإعادة الجدولة المُعادة تحط بعد الأولى بقليل: بعدها لا قبلها.
الاستجابة: EmailResource
object'email'- دائمًا `email`. ويجيب الاستدعاءان بالرسالة كاملة لا بإقرار، فلا يلزم إعادة جلب أي شيء لرؤية ما تغيّر؛ و`emails.send` يعيد الشكل نفسه مضافًا إليه `replayed`.
idstring- المقبض `msg_…`. ثابت طوال عمر الرسالة وهو المعرّف الذي يأخذه كل استدعاء آخر عليها.
statusEmailStatus- تكون `cancelled` بعد الإلغاء و`scheduled` بعد إعادة الجدولة، بما في ذلك رسالة كانت `queued` فقط خلف نافذة تراجع، فإعادة الجدولة تحوّلها إلى جدولة حقيقية. ولا يمكن نقل أو إيقاف سوى الرسائل في الحالتين `queued` و`scheduled`؛ وأي شيء تجاوز ذلك يعطي `conflict_error` برمز `email_not_cancellable`، لأن جزءًا منه صار في صندوق بريد أحدهم بالفعل.
scheduledAtstring | null- اللحظة بصيغة ISO التي يُتوقع أن تُرسل فيها الرسالة. وتُضبط لنافذة التراجع كما تُضبط لإرسال بـ `scheduledAt`، لأن الاثنين آلية واحدة، وتكون null في إرسال فوري بسيط.
cancellableUntilstring | null- متى يتوقف الإلغاء عن العمل، وهي اللحظة نفسها التي تحملها `scheduledAt` في كلا المسارين المؤجَّلين. وتكون null في إرسال فوري يكون قد انطلق بالفعل قبل أن يعود الاستدعاء.
sentAtstring | null- متى انطلقت الرسالة فعلًا. تكون null ما دامت تنتظر، وnull إلى الأبد في رسالة مُلغاة.
messageIdstring | null- ترويسة Message-ID بحسب RFC 5322، وتكون null إلى أن توجد رسالة MIME، أي إنها null دائمًا في رسالة يمكن لهذين الاستدعاءين التصرف فيها. وهي ليست ما تخاطب به الواجهة، ولا ما يعود به ارتداد لاحق أيضًا: فخدمة الإرسال تعيد كتابة الترويسة عند الخروج.
threadIdstring | null- المحادثة التي تنتمي إليها هذه الرسالة، مأخوذة من الطلب ومُعاد كتابتها بما يبلّغ عنه النقل بمجرد الإرسال. وتكون null عندما لا تكون الرسالة ردًا.
transportEmailTransport | (string & {}) | null- كيف خرجت البايتات، وتكون null حتى الإرسال، أي null على كل رسالة يمكن أن يعيدها إلغاء أو إعادة جدولة. والإرسال في وضع الاختبار يسجّل `test`، ويبقى الاتحاد مفتوحًا فلا تكون وسيلة نقل لا تسمّيها SDK بعد تغييرًا كاسرًا.
attemptsnumber- كم مرة طالب الإرسال بهذا السجل. تُزاد بالمطالبة لا بإرسال ناجح، وتكون 0 لأي شيء ما زال ينتظر.
lastErrorstring | null- آخر فشل سُجّل على الرسالة، وnull ما دام لم يفشل شيء. والإرسال المؤجَّل الذي تعذّر إدراج مهمته في الطابور يُكتب هنا بالشكل `Could not schedule: …` ويُنقل إلى `failed`، وهو السبيل الوحيد الذي تتوقف به رسالة مجدولة عن كونها قابلة للإلغاء دون أن يطلب أحد ذلك.
fromstring- العنوان الذي أُذن للرسالة بالخروج تحته، مخزَّنًا مجردًا وبأحرف صغيرة. وليس دائمًا العنوان المطلوب (فمفتاح مقيّد لا يسمي `from` يُحلّ إلى أول عنوان يجوز له استخدامه)، وأي اسم معروض يُسقط هنا، لأن مرشِّح `from` في `emails.list` يقارن بالمساواة.