المسوّدات
`drafts.list` و`list_all` و`iterate` و`get` و`create` و`update` و`delete`.
كل الدوالّ
page = client.drafts.list(query: "invoice", limit: 25)draft = client.drafts.get("draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8")puts page.items.size, draft[:subject] created = client.drafts.create( to: ["[email protected]"], cc: [], bcc: [], subject: "Your September invoice", html: "<p>Draft body.</p>", from: "[email protected]", threadId: "CAHk7pQ2x9LmZ4-mail.example.com") updated = client.drafts.update(created[:id], subject: "Revised")client.drafts.delete(updated[:id])يحتفظ update بمعرّف المسودة، فالقيمة التي يجيب بها هي دائمًا التي مرّرتها. والمعرّف المجهول يعطي 404، يُرفع في صورة OpenEmail::NotFoundError، لا مسودة جديدة.
حقول المسودة وسائط مسمّاة بأسماء API، فالمحادثة التي ترد عليها المسودة هي threadId:. ويمكن تمريرها أيضًا في Hash واحد. وتعود المسودة في صورة Hash بمفاتيح من نوع Symbol، فيقرأ draft[:subject] الموضوع. وكل كتابة تجيب بـ object وid فقط، فاقرأ المسودة كاملة عبر get.
يرقّم list الصفحات كما يفعل threads.list. فيعود pageToken الخاص بـ API بوصفه next_cursor ويدخل بوصفه cursor:، ويتبعه list_all وiterate نيابةً عنك. ويمرّر iterate كل مسودة إلى كتلة، أو يعيد Enumerator دونها. وتحمل الصفحة 25 مسودة ما لم يطلب limit: حتى 100. ويأخذ query: صياغة البحث الخاصة بـ threads.list، ولا يخرج البحث أبدًا عن المسودات. والصف مجرد object وid، فاستدعِ get للحصول على المستلمين والموضوع والمتن.
لا تذكر قائمة المسودات hasMore، فتكون قيمة has_more? هي true كلما عاد مؤشر. ويقدّم الخادم مؤشرًا كلما امتلأت صفحة، فالصفحة الأخيرة التي تصادف أنها ممتلئة تليها صفحة فارغة واحدة.
تُخزَّن المسودة كمحادثة تحمل التسمية DRAFT، ولهذا يسرد client.threads.list(folder: "draft") المسودات نفسها. ويجيب get وupdate وdelete على معرّف محادثة عادية بـ 404، مع أن threads.get يفتحه. ويحذف delete المسودة نهائيًا. فهي لا تذهب إلى سلة المهملات ولا يمكن التراجع.
لإرسال مسودة، مرّر معرّفها إلى emails.send بوصفه draftId:. فالمسودة توفر المحتوى والإرسال يوفر المُغلَّف. ولا يمكن جمع المسودة مع template أو translate.
client.emails.send( from: "[email protected]", to: "[email protected]", draftId: "draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8")المعاملات: drafts.create وdrafts.update
toArray<String>- عناوين المستلمين في صورة Array من String، لا صيغ Hash التي يقبلها `emails.send`، لأن نقطة النهاية هذه تضم الـ Array في القائمة المفصولة بفواصل التي يريدها المُشغِّل. ويمكن أن يحمل الـ String اسمًا معروضًا، كما في `Ada Lovelace <[email protected]>`، لكن الاسم الذي يحتوي فاصلة ينقسم إلى مستلمَين معطوبين. وبخلاف `emails.send`، لا يغلّف الـ gem هنا String منفردًا في Array، فمرّر `["[email protected]"]`. وعند الإنشاء تُحفظ الـ Array المحذوفة فارغة. وعند التحديث يترك الحقل المحذوف المستلمين المخزَّنين كما هم، لأن المعالج يقرأ المسودة أولًا ثم يدمج.
ccArray<String>- عناوين Cc، بالصيغة نفسها التي لـ `to`. فارغة عند الإنشاء إذا حُذفت، ولا تُمسّ عند التحديث إذا حُذفت.
bccArray<String>- عناوين Bcc، بالصيغة نفسها التي لـ `to`. فارغة عند الإنشاء إذا حُذفت، ولا تُمسّ عند التحديث إذا حُذفت.
subjectString- موضوع المسودة، بحد أقصى 998 حرفًا، وهو حد السطر في RFC 5322. وعند الإنشاء يكون افتراضيًا String فارغًا، والموضوع الفارغ يُخزَّن بوصفه `(no subject)`، فيكون للمسودة موضوع دائمًا.
htmlString- متن المسودة كترميز، بحد أقصى 1,000,000 حرف. وهو المتن الغالب. إذ يغذّي `html` و`text` حقل الرسالة الوحيد لدى المُشغِّل، فإرسال الاثنين يخزّن هذا.
textString- متن نصي عادي، بحد أقصى 1,000,000 حرف، ولا يُستخدم إلا في غياب `html`. والمسودة تخزّن متنًا واحدًا لا جزأين، فالنص المرسل هنا يعود دون تحويل في `html` عند قراءة المسودة.
fromString- عنوان المرسل المراد حفظه على المسودة، مع اسم معروض أو دونه. وإن حُذف عند الإنشاء، لا يكون للمسودة مرسل. وعند التحديث يُنقل من المسودة المخزَّنة إذا حُذف. فالمُشغِّل يعيد بناء الرسالة كاملة مما يُسلَّم إليه، ومن ثَم فإن تعديلًا جزئيًا يُسقطه كان سيغيّر المرسل المختار بصمت. وString فارغ أو nil عند التحديث يمسحه.
threadIdString- اربط المسودة بمحادثة قائمة لتُحفظ كرد. ومثل `from`، يُنقل عند التحديث إذا حُذف، لأن إعادة بناء الرسالة بدونه كانت ستفصل الرد عن محادثته. وString فارغ عند التحديث يفصلها. وتبقى المسودة مع ذلك مخزَّنة كمحادثة مستقلة بمعرّفها الخاص، فتُسرد مع المسودات لا داخل المحادثة التي ترد عليها.
اترك الحقل لتحتفظ به. وتمرير nil ليس كذلك. فالـ gem يرسله، وكل حقل يرفضه بالخطأ 422 invalid_parameter باستثناء from عند التحديث، حيث يمسح nil المرسل. استدعِ compact على Hash القيم الاختيارية قبل أن تمرّره. والمتن صارم أيضًا. فأي حقل خارج هذه الثمانية يُرفض بالطريقة نفسها، ولا يوجد حقل للمرفقات.
الاستجابة: مسودة (drafts.get)
objectString- دائمًا `draft`.
idString- معرّف المسودة، `draft-` متبوعًا بـ UUID. وتجيب عمليات الكتابة بـ `object` و`id` فقط لا بالمسودة كاملة، فاقرأ المعرّف من النتيجة بدل إعادة استخدام المعرّف الذي أرسلته.
toArray<String>- عناوين المستلمين كما خزّنتها المسودة، مجردة، مع حذف أي اسم معروض. Array فارغة، لا nil أبدًا، حين لا يكون في المسودة أي عنوان.
ccArray<String>- عناوين Cc كما خُزّنت. Array فارغة، لا nil أبدًا، حين لا يكون في المسودة أي عنوان.
bccArray<String>- عناوين Bcc كما خُزّنت. Array فارغة، لا nil أبدًا، حين لا يكون في المسودة أي عنوان.
subjectString- الموضوع المخزَّن، لا يكون nil أبدًا. والمسودة المحفوظة دون موضوع تُقرأ `(no subject)`، وهي القيمة البديلة التي يخزّنها صندوق البريد، فقارن بها بدل التحقق من String فارغ.
htmlString- المتن المخزَّن، أو String فارغ حيث لا يكون للمسودة متن. ولا يوجد حقل نص منفصل في الخرج، فالمسودة المحفوظة بـ `text` وحده تُعاد هنا.
fromString or nil- العنوان الذي حُفظت به المسودة، ولا يُبلَّغ عنه إلا ما دامت مساحة العمل قادرة على الإرسال باسمه. ويكون nil لمسودة حُفظت دون مرسل أو من عنوان أُزيل منذ ذلك الحين.
threadIdString or nil- المحادثة التي ترد عليها المسودة، أو nil لمسودة تبدأ محادثة جديدة.
attachmentsArray<Hash>- لكل عنصر `filename` و`contentType` فقط، لأن مرفقات المسودات تُخزَّن كأسماء وأنواع بلا محتوى. وأي `update` يفرغ هذه القائمة.