SDK

زمان‌بندی و لغو

`scheduledAt`، `emails.reschedule` و `emails.cancel`.

ارسال در آینده

schedule.ts

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. تا یک سال بعد، هرگز در گذشته.

جابه‌جایی و توقف

reschedule.ts

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 است، چون بخشی از آن پیش از این در صندوق کسی است. لغوِ پیامی که از پیش لغو شده موفق می‌شود و چیزی را تغییر نمی‌دهد.

به‌جایش یک پنجرهٔ لغو

undo-window.ts

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` رد می‌شود، که از پیش تا وقتی نرفته قابل لغو است، و پیامی که این‌طور نگه داشته شود به‌جای `scheduled` روی `queued` می‌نشیند. همان سازوکار تعویق است با تأخیری کوتاه.
idstringالزامی: شناسهٔ `msg_…`، و نخستین آرگومان هر دو فراخوانی `emails.cancel` و `emails.reschedule`. هر دو به‌جای scope ای از آنِ خودشان به `emails:send` نیاز دارند، و هر دو درون workspace خودِ کلید حل می‌شوند، پس شناسه‌ای متعلق به workspace دیگر دقیقاً مثل شناسه‌ای که هرگز وجود نداشته یک `not_found_error` است.
reschedule.scheduledAtDate | stringالزامی: زمان تازه، به‌عنوان آرگومان دوم `emails.reschedule`، که با همان قواعد و در برابر همان پنجرهٔ یک‌ساله تفسیر می‌شود، و تنها چیزی است که `PATCH /emails/{id}` زیرین تغییرش می‌دهد. مدت نسبت به زمانی است که SERVER آن را می‌خواند، پس زمان‌بندی دوباره‌ای که بازفرستاده شود کمی دیرتر از اولی می‌نشیند: دیرتر، هرگز زودتر.

پاسخ: EmailResource

object'email': همیشه `email`. هر دو فراخوانی به‌جای یک تأییدیه با کل پیام پاسخ می‌دهند، پس برای دیدن آنچه تغییر کرده لازم نیست چیزی دوباره گرفته شود؛ `emails.send` همین شکل را به‌علاوهٔ `replayed` برمی‌گرداند.
idstring: دستگیرهٔ `msg_…`. تا پایان عمر پیام پایدار است و همان شناسه‌ای است که هر فراخوانی دیگری روی آن می‌گیرد.
statusEmailStatus: پس از یک cancel برابر `cancelled` و پس از یک reschedule برابر `scheduled`، از جمله برای پیامی که فقط پشت یک پنجرهٔ لغو `queued` بوده و reschedule آن را به زمان‌بندی واقعی تبدیل می‌کند. فقط پیام‌های `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، که تا وقتی MIME وجود نداشته باشد null است، پس روی هر پیامی که این دو فراخوانی بتوانند رویش کار کنند همیشه null است. چیزی نیست که با آن API را خطاب کنید، و چیزی هم نیست که bounce بعدی با آن برگردد: سرویس ارسال هدر را در مسیر خروج بازنویسی می‌کند.
threadIdstring | null: thread ای که این پیام به آن تعلق دارد، که از درخواست گرفته می‌شود و به محض ارسال با هر چه حمل‌ونقل گزارش کند بازنویسی می‌شود. وقتی پاسخ نباشد null است.
transportEmailTransport | (string & {}) | null: بایت‌ها چگونه رفتند، که تا پیش از ارسال null است، پس روی هر پیامی که cancel یا reschedule بتواند برگرداند null است. ارسال در حالت test مقدار `test` را ثبت می‌کند، و union باز می‌ماند تا حمل‌ونقلی که این SDK هنوز نامش را نمی‌برد تغییری شکننده نباشد.
attemptsnumber: چند بار ارسال این ردیف را claim کرده است. با claim افزایش می‌یابد نه با ارسال موفق، و برای هر چیزی که هنوز منتظر است 0 است.
lastErrorstring | null: آخرین شکست ثبت‌شده در برابر پیام، که تا وقتی چیزی شکست نخورده null است. ارسالی به‌تعویق‌افتاده که کارش نتوانسته صف شود همین‌جا به شکل `Could not schedule: …` نوشته و به `failed` منتقل می‌شود، و این تنها راهی است که پیامی زمان‌بندی‌شده بدون درخواست کسی از قابل‌لغو بودن می‌افتد.
fromstring: نشانی‌ای که پیام مجاز شمرده شد با آن بیرون برود، که خام و با حروف کوچک ذخیره می‌شود. همیشه همان نشانی درخواست‌شده نیست (کلیدی محدودشده که هیچ `from` ای را نام نبرد به نخستین نشانی‌ای که اجازه‌اش را دارد حل می‌شود)، و هر نام نمایشی اینجا انداخته می‌شود، چون فیلتر `from` در `emails.list` بر اساس برابری مقایسه می‌کند.