المسوّدات
`drafts->list` و`listAll` و`iterate` و`get` و`create` و`update` و`delete`.
كل الدوالّ
$page = $client->drafts->list(query: 'invoice', limit: 25);$draft = $client->drafts->get('draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8');echo count($page), ' ', $draft['subject'], PHP_EOL; $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، يُرمى في صورة NotFoundException، لا مسودة جديدة.
حقول المسودة مفاتيح مصفوفة واحدة بأسماء API، فالمحادثة التي ترد عليها المسودة هي threadId. وتعود المسودة في صورة مصفوفة مفاتيحها بصيغة camelCase، فيقرأ $draft['subject'] الموضوع. وكل كتابة تجيب بـ object وid فقط، فاقرأ المسودة كاملة عبر get.
يرقّم list الصفحات كما يفعل threads->list. فيعود pageToken الخاص بـ API بوصفه nextCursor ويدخل بوصفه cursor:، ويتبعه listAll وiterate نيابةً عنك. ويعيد iterate كائن Generator يسلّم مسودة واحدة في كل مرة. وتحمل الصفحة 25 مسودة ما لم يطلب limit: حتى 100. ويأخذ query: صياغة البحث الخاصة بـ threads->list، ولا يخرج البحث أبدًا عن المسودات. والصف مجرد object وid، فاستدعِ get للحصول على المستلمين والموضوع والمتن.
لا تذكر قائمة المسودات hasMore، فتكون قيمة hasMore هي 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- عناوين المستلمين في صورة قائمة من السلاسل النصية، لا صيغ المصفوفات التي يقبلها `emails->send`، لأن نقطة النهاية هذه تضم القائمة في السلسلة المفصولة بفواصل التي يريدها المُشغِّل. ويمكن أن تحمل السلسلة النصية اسمًا معروضًا، كما في `Ada Lovelace <[email protected]>`، لكن الاسم الذي يحتوي فاصلة ينقسم إلى مستلمَين معطوبين. وبخلاف `emails->send`، لا يغلّف العميل هنا سلسلة نصية منفردة في قائمة، فمرّر `['[email protected]']`. وعند الإنشاء تُحفظ القائمة المحذوفة فارغة. وعند التحديث يترك الحقل المحذوف المستلمين المخزَّنين كما هم، لأن المعالج يقرأ المسودة أولًا ثم يدمج.
ccarray- عناوين Cc، بالصيغة نفسها التي لـ `to`. فارغة عند الإنشاء إذا حُذفت، ولا تُمسّ عند التحديث إذا حُذفت.
bccarray- عناوين Bcc، بالصيغة نفسها التي لـ `to`. فارغة عند الإنشاء إذا حُذفت، ولا تُمسّ عند التحديث إذا حُذفت.
subjectstring- موضوع المسودة، بحد أقصى 998 حرفًا، وهو حد السطر في RFC 5322. وعند الإنشاء يكون افتراضيًا سلسلة نصية فارغة، والموضوع الفارغ يُخزَّن بوصفه `(no subject)`، فيكون للمسودة موضوع دائمًا.
htmlstring- متن المسودة كترميز، بحد أقصى 1,000,000 حرف. وهو المتن الغالب. إذ يغذّي `html` و`text` حقل الرسالة الوحيد لدى المُشغِّل، فإرسال الاثنين يخزّن هذا.
textstring- متن نصي عادي، بحد أقصى 1,000,000 حرف، ولا يُستخدم إلا في غياب `html`. والمسودة تخزّن متنًا واحدًا لا جزأين، فالنص المرسل هنا يعود دون تحويل في `html` عند قراءة المسودة.
fromstring or null- عنوان المرسل المراد حفظه على المسودة، مع اسم معروض أو دونه. وإن حُذف عند الإنشاء، لا يكون للمسودة مرسل. وعند التحديث يُنقل من المسودة المخزَّنة إذا حُذف. فالمُشغِّل يعيد بناء الرسالة كاملة مما يُسلَّم إليه، ومن ثَم فإن تعديلًا جزئيًا يُسقطه كان سيغيّر المرسل المختار بصمت. والسلسلة النصية الفارغة أو null عند التحديث تمسحه.
threadIdstring- اربط المسودة بمحادثة قائمة لتُحفظ كرد. ومثل `from`، يُنقل عند التحديث إذا حُذف، لأن إعادة بناء الرسالة بدونه كانت ستفصل الرد عن محادثته. والسلسلة النصية الفارغة عند التحديث تفصلها. وتبقى المسودة مع ذلك مخزَّنة كمحادثة مستقلة بمعرّفها الخاص، فتُسرد مع المسودات لا داخل المحادثة التي ترد عليها.
اترك الحقل لتحتفظ به. وتمرير null ليس كذلك. فالعميل يرسله، وكل حقل يرفضه بالخطأ 422 invalid_parameter باستثناء from عند التحديث، حيث يمسح null المرسل. مرّر مصفوفة القيم الاختيارية عبر array_filter($fields, static fn(mixed $value): bool => $value !== null) قبل أن تمرّرها. والمتن صارم أيضًا. فأي حقل خارج هذه الثمانية يُرفض بالطريقة نفسها، ولا يوجد حقل للمرفقات.
الاستجابة: مسودة (drafts->get)
objectstring- دائمًا `draft`.
idstring- معرّف المسودة، `draft-` متبوعًا بـ UUID. وتجيب عمليات الكتابة بـ `object` و`id` فقط لا بالمسودة كاملة، فاقرأ المعرّف من النتيجة بدل إعادة استخدام المعرّف الذي أرسلته.
toarray- عناوين المستلمين كما خزّنتها المسودة، مجردة، مع حذف أي اسم معروض. قائمة فارغة، لا null أبدًا، حين لا يكون في المسودة أي عنوان.
ccarray- عناوين Cc كما خُزّنت. قائمة فارغة، لا null أبدًا، حين لا يكون في المسودة أي عنوان.
bccarray- عناوين Bcc كما خُزّنت. قائمة فارغة، لا null أبدًا، حين لا يكون في المسودة أي عنوان.
subjectstring- الموضوع المخزَّن، لا يكون null أبدًا. والمسودة المحفوظة دون موضوع تُقرأ `(no subject)`، وهي القيمة البديلة التي يخزّنها صندوق البريد، فقارن بها بدل التحقق من سلسلة نصية فارغة.
htmlstring- المتن المخزَّن، أو سلسلة نصية فارغة حيث لا يكون للمسودة متن. ولا يوجد حقل نص منفصل في الخرج، فالمسودة المحفوظة بـ `text` وحده تُعاد هنا.
fromstring or null- العنوان الذي حُفظت به المسودة، ولا يُبلَّغ عنه إلا ما دامت مساحة العمل قادرة على الإرسال باسمه. ويكون null لمسودة حُفظت دون مرسل أو من عنوان أُزيل منذ ذلك الحين.
threadIdstring or null- المحادثة التي ترد عليها المسودة، أو null لمسودة تبدأ محادثة جديدة.
attachmentsarray- لكل عنصر `filename` و`contentType` فقط، لأن مرفقات المسودات تُخزَّن كأسماء وأنواع بلا محتوى. وأي `update` يفرغ هذه القائمة.