Ruby

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

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

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

schedule.rb

message = {from: "[email protected]", to: "[email protected]", subject: "Your September invoice", text: "Invoice attached."} client.emails.send(message, scheduledAt: "PT1H")client.emails.send(message, scheduledAt: Time.utc(2027, 1, 1, 9))client.emails.send(message, scheduledAt: "2027-01-01T09:00:00.000Z")

یک Time یا DateTime، یک لحظهٔ ISO 8601 به‌صورت String، یا مدتی مانند PT1H یا P2D. تا یک سال بعد، هرگز در گذشته. یک آرگومان کلیدواژه‌ای در کنار Hash، فیلد را به پیامی که پیش‌تر ساخته‌اید می‌افزاید.

یک Date در Ruby به‌صورت تاریخ خالی مانند 2027-01-01 فرستاده می‌شود، که API آن را نیمه‌شب UTC همان روز می‌خواند. وقتی ساعت مهم است، یک Time مانند Time.utc(2027, 1, 1, 9) بدهید.

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

reschedule.rb

message = {from: "[email protected]", to: "[email protected]", subject: "Your September invoice", text: "Invoice attached."} queued = client.emails.send(message, scheduledAt: "PT1H") client.emails.reschedule(queued[:id], Time.now + 86_400)client.emails.cancel(queued[:id])

فقط پیام‌های queued و scheduled را می‌شود متوقف کرد. هر چیزی جلوتر از آن یک OpenEmail::ConflictError را raise می‌کند، چون بخشی از آن پیش از این در صندوق کسی است. لغوِ پیامی که از پیش لغو شده موفق می‌شود و چیزی را تغییر نمی‌دهد.

برای یافتن آنچه در یک بازه منتظر رفتن است، با status: ["scheduled", "queued"] و scheduled_from: و scheduled_to: فهرست بگیرید، همان‌طور که تقویم برنامه انجام می‌دهد.

تغییر آن پیش از رفتن

emails.update پیامی را که هنوز نرفته تغییر می‌دهد: زمان رفتنش را با scheduledAt، آنچه می‌گوید را با subject، html و text، نشانی‌ای که از آن می‌رود را با from، و اینکه به چه کسانی می‌رود را با to، cc و bcc. هر ترکیبی از آن‌ها را با هم بفرستید، و فیلدی که جا بگذارید مقدارش را نگه می‌دارد. یک فهرست گیرندگان، فهرست ذخیره‌شده را به‌طور کامل جایگزین می‌کند. این همان کاری است که ویرایش یک پیام زمان‌بندی‌شده در تقویم برنامه انجام می‌دهد.

update.rb

updated = client.emails.update(  "msg_3f9a1c07d2b84e6a9c5b1f20",  subject: "Your September invoice, corrected",  to: ["[email protected]", "[email protected]"],  scheduledAt: Time.utc(2026, 10, 5, 8)) puts updated[:status], updated[:subject], updated[:scheduledAt]

from همان‌طور بررسی می‌شود که در ارسال، پس باید نشانی‌ای باشد که کلید اجازهٔ ارسال با آن را دارد. پیامی که هنگام پذیرفته شدن ترجمه شده متن تأییدشده‌اش را نگه می‌دارد، پس subject، html یا text تازه روی آن یک 409 translation_locked است، و پیامی که پیش از زمان‌بندی رمزگذاری شده متن و گیرندگانش را نگه می‌دارد. این پیام‌ها را لغو کنید و به‌جایش دوباره بفرستید.

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

undo_window.rb

message = {from: "[email protected]", to: "[email protected]", subject: "Your September invoice", text: "Invoice attached."} held = client.emails.send(message, cancellableForSeconds: 30) puts held[:status], held[:cancellableUntil]

پیام زمان‌بندی‌شده تا وقتی نرفته از پیش قابل لغو است، پس این دو را نمی‌شود با هم به کار برد و سرور ردش می‌کند. این یکی را برای پنجرهٔ لغو ارسال روی یک پیام فوری به کار ببرید.

پارامترها: زمان‌بندی

scheduledAtTime, DateTime or String: زمان ارسال، روی `emails.send`: یک Time یا DateTime، یک لحظهٔ ISO 8601 به‌صورت String، یا مدتی مانند `PT1H` یا `P2D`. Time یا DateTime به‌صورت لحظهٔ UTC فرستاده می‌شود، String همان‌طور که هست، و Date در Ruby به‌صورت تاریخ خالی که یعنی نیمه‌شب UTC. دست‌کم یک ثانیه در آینده و حداکثر 365 روز بعد، که گذشتن از هر دو کران یک `validation_error` روی `scheduledAt` است، و زبان طبیعی پذیرفته نمی‌شود، چون تفسیر نادرستِ «سه‌شنبهٔ بعد» پیامی را در زمانی می‌فرستد که دیگر نمی‌شود پسش گرفت.
cancellableForSecondsInteger: پنجرهٔ لغو ارسال روی یک ارسال «فوری»: یک Integer از 0 تا 900 با پیش‌فرض 0. هر مقدار بالای 0 در کنار `scheduledAt` رد می‌شود، که از پیش تا وقتی نرفته قابل لغو است، و پیامی که این‌طور نگه داشته شود به‌جای `scheduled` روی `queued` می‌نشیند. همان سازوکار تعویق است با تأخیری کوتاه.
idStringالزامی: شناسهٔ `msg_`، و نخستین آرگومان `emails.cancel`، `emails.reschedule` و `emails.update`. این‌ها به‌جای اسکوپی از آنِ خودشان به `emails:send` نیاز دارند، و شناسه را درون فضای کاری خودِ کلید جست‌وجو می‌کنند، پس شناسه‌ای متعلق به فضای کاری دیگر دقیقاً مثل شناسه‌ای که هرگز وجود نداشته یک `not_found_error` است.
scheduled_atTime, DateTime or Stringالزامی: زمان تازه، به‌عنوان آرگومان دوم `emails.reschedule`، که با همان قواعد و در برابر همان پنجرهٔ یک‌ساله خوانده می‌شود. تنها چیزی است که `reschedule` تغییر می‌دهد، و کلاینت چیز دیگری نمی‌فرستد. مدت نسبت به زمانی است که «سرور» آن را می‌خواند، پس زمان‌بندی دوباره‌ای که دوباره تلاش شود کمی دیرتر از اولی می‌نشیند: دیرتر، هرگز زودتر.
api_keyString: روی هر یک از این سه فراخوانی، به‌جای کلید کلاینت با این کلید عمل می‌کند.

پاسخ

cancel، reschedule و update هرکدام کل پیام را به‌صورت یک Hash با کلیدهای Symbol برمی‌گردانند.

objectString: همیشه `email`. این فراخوانی‌ها به‌جای یک تأییدیه با کل پیام پاسخ می‌دهند، پس برای دیدن آنچه تغییر کرده لازم نیست چیزی دوباره گرفته شود. `emails.send` همین شکل را به‌علاوهٔ `replayed` برمی‌گرداند.
idString: دستگیرهٔ `msg_`. تا پایان عمر پیام پایدار است و همان شناسه‌ای است که هر فراخوانی دیگری روی آن می‌گیرد.
statusString: پس از لغو برابر `cancelled` و پس از زمان‌بندی دوباره برابر `scheduled`، از جمله برای پیامی که فقط پشت یک پنجرهٔ لغو `queued` بوده و زمان‌بندی دوباره آن را به زمان‌بندی واقعی تبدیل می‌کند. فقط پیام‌های `queued` و `scheduled` را می‌شود جابه‌جا یا متوقف کرد. هر چیزی جلوتر از آن یک `conflict_error` با کد `email_not_cancellable` است، چون بخشی از آن پیش از این در صندوق کسی است.
scheduledAtString or nil: لحظهٔ ISO 8601 که پیام باید روانه شود. هم برای پنجرهٔ لغو تنظیم می‌شود و هم برای ارسال با `scheduledAt`، چون این دو یک سازوکارند، و روی ارسال فوریِ ساده nil است.
cancellableUntilString or nil: زمانی که لغو دیگر کار نمی‌کند، که روی هر دو مسیر تعویق همان لحظهٔ `scheduledAt` است. روی ارسال فوری nil است، که تا وقتی فراخوانی برگردد پیش از این رفته است.
sentAtString or nil: زمانی که پیام واقعاً رفت. تا وقتی منتظر است nil است، و روی پیامی که لغو شده برای همیشه nil.
messageIdString or nil: همان Message-ID مربوط به RFC 5322، که تا وقتی MIME وجود نداشته باشد nil است، پس روی هر پیامی که این فراخوانی‌ها بتوانند رویش کار کنند همیشه nil است. چیزی نیست که با آن API را خطاب کنید، و چیزی هم نیست که bounce بعدی با آن برگردد: سرویس ارسال سرآیند را در مسیر خروج بازنویسی می‌کند.
threadIdString or nil: رشته‌ای که این پیام به آن تعلق دارد، که از درخواست گرفته می‌شود و به محض ارسال با هر چه لایهٔ انتقال گزارش کند بازنویسی می‌شود. وقتی پاسخ نباشد nil است.
transportString or nil: بایت‌ها چگونه رفتند، که تا پیش از ارسال nil است، پس روی هر پیامی که لغو یا زمان‌بندی دوباره بتواند برگرداند nil است. ارسال در حالت test مقدار `test` را ثبت می‌کند، و ممکن است لایهٔ انتقالی ظاهر شود که این gem هنوز نامش را نمی‌برد، پس با مقدار ناشناخته به‌عنوان اطلاعات رفتار کنید نه خطا.
attemptsInteger: چند بار فرایند ارسال این ردیف را برداشته است. با هر برداشتن بالا می‌رود نه با ارسال موفق، و برای هر چیزی که هنوز منتظر است 0 است.
lastErrorString or nil: آخرین شکست ثبت‌شده برای پیام، که تا وقتی چیزی شکست نخورده nil است. ارسالی به‌تعویق‌افتاده که کارش نتوانسته در صف قرار گیرد همین‌جا به شکل `Could not schedule: …` نوشته و به `failed` منتقل می‌شود، و این تنها راهی است که پیامی زمان‌بندی‌شده بدون درخواست کسی از قابل‌لغو بودن می‌افتد.
fromString: نشانی‌ای که پیام مجاز شمرده شد با آن بیرون برود: همان `from` ارسال‌شده، که خام و با حروف کوچک ذخیره می‌شود. هر نام نمایشی اینجا انداخته می‌شود، چون فیلتر `from:` در `emails.list` بر اساس برابری مقایسه می‌کند.