المحادثات والمسودات والتسميات

أوامر البريد، مثل inbox وread وarchive وlabel add، مكتوبة للبشر: تأخذ عدة معرّفات محادثات دفعة واحدة، وتنسّق ما تطبعه، وتُبقي معرّفات التسميات بعيدًا عن النظر. وكل منها يشغّل أوامر من هذه الصفحة، وهي طرق SDK للمحادثات والمسودات والتسميات، أمر لكل طريقة، فيصبح threads.listAttachments هو openemail threads list-attachments.

استخدم هذه حين تحتاج إلى ما تتركه أوامر البريد: محادثة كما تعيدها API تمامًا، والملفات المرفقة برسالة، والمسودات، وإنشاء التسميات وإعادة تسميتها وتغيير ألوانها وحذفها.

• —يعمل openemail thread وopenemail draft كما تعمل صيغ الجمع. أما openemail labels فلا صيغة مفرد له: openemail label هو أمر البريد الذي يضع التسميات على المحادثات.
• —تقبل الأفعال الأسماء البديلة المعتادة: ls بدلًا من list، وshow وview بدلًا من get، وnew وadd بدلًا من create، وedit بدلًا من update، وrm وdel وremove بدلًا من delete.
• —كل خيار موجود في openemail <namespace> <verb> --help، مثل openemail threads list --help.

المحادثات في صندوق البريد. معرّف المحادثة مثل CAHk7pQ2x9LmZ4 يأتي من threads list أو openemail inbox أو openemail search.

• —القيمة الافتراضية لـ --folder هي inbox، ويُطابَق كمعرّف تسمية، لذا تعمل sent وarchive وspam وtrash وdraft وsnoozed وstarred وunread، وتُقرأ bin على أنها trash، ويعمل أيضًا معرّف تسمية مستخدم مثل USER_RECEIPTS. والمجلد الذي لا يطابق شيئًا يعيد صفحة فارغة، لا خطأ.
• —يأخذ --query صياغة البحث في التطبيق، ويبحث in:anywhere في كل مجلد. ويضيّق --label-ids أكثر، إذ يجب أن تحمل المحادثة المجلد وكل معرّف تمرّره. ويقرأ --date-from و--date-to أحدث رسالة في كل محادثة، والطرفان مشمولان.
• —يضم threads get ردود المسودات غير المرسلة بين الرسائل، معلَّمة بـ isDraft: true، ويفتح معرّف مسودة أيضًا.
• —يحتاج threads update إلى --read أو --no-read أو تسمية لإضافتها أو إزالتها. تُطبَّق الإزالات قبل الإضافات. ومعرّف التسمية الذي لا يسمّي تسمية يُرفض بـ label_not_found ولا يتغير شيء في المحادثة، لذا أنشئ التسمية أولًا. وتُرفض TRASH وSNOOZED وDRAFT بـ label_not_directly_settable: استخدم threads trash وthreads snooze.
• —لا يحذف threads trash شيئًا، وتبقى المحادثة قابلة للقراءة عبر threads get، لكن لا يوجد أمر يُخرج محادثة من سلة المهملات. ونقل محادثة مؤجَّلة إلى المهملات يلغي استيقاظها أيضًا.
• —يرسل threads snooze القيمة <wake-at> كما هي، لذا أعطه لحظة مستقبلية بصيغة ISO 8601 مع Z أو إزاحة، لأن الوقت الذي يخلو منهما يُقرأ بالمنطقة الزمنية للخادم. والمهلة مثل 3h تُرفض لأنها غير صالحة. أما openemail snooze --until 3h فيقبل مهلة. وتستيقظ المحادثات في مسح يجري كل ساعة، بتأخير قد يبلغ نحو ساعة، وتعود دائمًا إلى الوارد.
• —يعيد threads list-attachments كل ملف كاملًا في استجابة واحدة. خذ معرّف الرسالة من messages في threads get. وتكون content سلسلة فارغة حين يتعذر العثور على البايتات المخزنة، لذا افحص طولها قبل فك الترميز.

رسائل غير مرسلة محفوظة في صندوق البريد. يبدأ معرّف المسودة بـ draft-.

• —يبحث drafts list --query في الموضوع والمرسل وبداية النص، ولا يخرج أبدًا عن المسودات. ويقرأ older_than:30d وبقية عوامل التاريخ وقت آخر حفظ للمسودة، ولا تطابق to: وcc: وbcc: شيئًا في المسودة.
• —تُخزَّن المسودة كمحادثة مسمّاة DRAFT، لذا يفتحها threads get ويسردها openemail inbox draft. ويرفض drafts get وupdate وdelete معرّف محادثة عادية بـ 404.
• —يحفظ openemail drafts create المجرد مسودة فارغة. لا يُفحص إلا الطول: موضوع حتى 998 حرفًا، و--html و--text حتى 1,000,000 لكل منهما، ويُحتفظ بـ --html حين يُضبط الاثنان. ولا يوجد خيار للمرفقات.
• —يستبدل drafts update كل حقل ترسله. والقائمة تستبدل المخزنة كلها، فـ --to مع عنوان واحد يُسقط البقية، وأي تحديث يفرغ قائمة مرفقات المسودة.
• —يسجّل --thread-id المحادثة التي ترد عليها المسودة، لكن المسودة تبقى مخزنة كمحادثة مستقلة.
• —تشغيل drafts create مرة أخرى يحفظ مسودة ثانية، لأنه لا يأخذ مفتاح لاتكرارية. والاسم المعروض الذي فيه فاصلة ينقسم إلى مستلمَين معطوبين، فاحذف الفاصلة.
• —يرسل openemail send --draft <id> --to <address> مسودة. يأتي النص من المسودة، وكذلك الموضوع ما لم تمرّر --subject، أما المستلمون فهم الذين تسمّيهم. ولا يمكن جمعه مع نص أو --template أو --translate.

التسميات التي يمكن أن تحملها المحادثة. معرّف تسمية المستخدم هو USER_ يليه الاسم الذي أُنشئت به، بأحرف كبيرة، مع تحويل كل سلسلة من المسافات إلى _، فيصبح Big Clients هو USER_BIG_CLIENTS.

• —المعرّف لا يتغير أبدًا، حتى بعد إعادة التسمية، لذا خزّن المعرّفات لا الأسماء.
• —تسميات النظام مثل INBOX وSTARRED وUNREAD لا تُسرد ولا يمكن تغييرها أو حذفها، مع أن threads update يقبلها. وlabels get على إحداها يعطي 404.
• —تضم مساحة العمل حتى 50 تسمية مستخدم. والاسم الذي تحمله تسمية أخرى بالفعل، دون اعتبار لحالة الأحرف، يُرفض بـ label_name_taken.
• —اللون قيمة ست عشرية مثل #3B82F6 أو رمز تدرج مثل gradient:sunset. ويأخذ --label-color اللون كله بصيغة JSON، و--label-color null يمسحه.
• —التسمية ملك لمساحة العمل، لذا فإن إعادة تسميتها أو تغيير لونها أو حذفها يغيّرها لكل من فيها.
• —لا تراجع عن labels delete. وإنشاء تسمية بالاسم نفسه من جديد يعطي المعرّف نفسه، لكن المحادثات لا تستعيدها. ويخبرك threadCount في labels get كم محادثة ستفقدها.

• —يأخذ أمر البريد عدة معرّفات محادثات ويبلّغ عن كل منها، ومع --json يطبع { results, succeeded, failed }. أما الأمر في هذه الصفحة فيأخذ معرّفًا واحدًا ويطبع ما تعيده API.
• —يقرأ openemail inbox كل محادثة يسردها ليعرض من كتب آخرًا والموضوع. أما threads list فيرسل طلبًا واحدًا لكل صفحة ولا يطبع إلا المعرّفات، وهذا كل ما يحتاجه خط المعالجة.
• —يحوّل openemail read رسالة HTML إلى نص ويعلّم المحادثة كمقروءة. أما threads get فيطبع المحادثة كما تعيدها API ولا يغيّر شيئًا.

علّم محادثة كمقروءة وأرشفها وضع عليها تسمية في طلب واحد، حيث كانت mark read وarchive وlabel add ستحتاج إلى ثلاثة:

openemail threads update CAHk7pQ2x9LmZ4 --read --add-label-ids ARCHIVE,USER_RECEIPTS --remove-label-ids INBOX --json

أنشئ تسمية ورتّب تحتها كل محادثة مطابقة. عند التمرير عبر أنبوب يطبع --all كائن JSON واحدًا في كل سطر:

openemail labels create --name Receipts --color-background-color gradient:meadowopenemail threads list --query "in:anywhere subject:receipt newer_than:1y" --all | jq -r .id | xargs openemail label add --label USER_RECEIPTS

احفظ ملفًا واحدًا من رسالة. معرّفات الرسائل موجودة في messages ضمن threads get:

openemail threads get CAHk7pQ2x9LmZ4 --json | jq -r ".messages[].id"openemail threads list-attachments CAHk7pQ2x9LmZ4 message_4c1b257a --json | jq -r '.[] | select(.filename == "invoice.pdf") | .content' | base64 --decode > invoice.pdf

اكتب مسودة، وغيّرها، واقرأها من جديد، ثم أرسلها:

DRAFT=$(openemail drafts create --to [email protected] --subject "Engine notes for Thursday" --html "<p>Agenda below.</p>" --json | jq -r .id)openemail drafts update "$DRAFT" --to [email protected],[email protected]openemail drafts get "$DRAFT"openemail send --draft "$DRAFT" --from [email protected] --to [email protected],[email protected]

تخلّص من المسودات التي لم يحفظها أحد منذ 30 يومًا. يطبع التشغيل التجريبي كل DELETE دون إرساله، ويجيب --yes عن التأكيد:

openemail drafts list --query older_than:30d --all | jq -r .id > stale.txtxargs -n 1 openemail drafts delete --dry-run < stale.txtxargs -n 1 openemail drafts delete --yes < stale.txt

اختر تدرجًا من لوحة الألوان، وعاين التغيير، ونفّذه، ثم أزل اللون لاحقًا:

openemail labels list-colors --json | jq -r '.[] | select(.kind == "gradient") | .value'openemail labels update USER_RECEIPTS --name "Receipts 2026" --color-background-color gradient:aurora --dry-runopenemail labels update USER_RECEIPTS --name "Receipts 2026" --color-background-color gradient:auroraopenemail labels update USER_RECEIPTS --label-color null

النطاق الناقص يتوقف برمز الخروج 4. ولا يطلب أي من هذه الأوامر رمز تحقق، سواء مع تسجيل الدخول عبر المتصفح أو مع مفتاح API.

تسجيل الدخول أو المفتاح المقيّد ببعض العناوين لا يرى إلا المحادثات المسلَّمة إليها، وأي محادثة أخرى تعطي 404، كأنها غير موجودة. والتسميات ملك لمساحة العمل، لذا يظل يرى كل تسمية، لكن threadCount لا يعدّ إلا المحادثات التي يستطيع رؤيتها.

• —تقرأ threads list وdrafts list وlabels list صفحة واحدة، 25 ما لم يحدد --limit غير ذلك، حتى 100. ويواصل --cursor من المؤشر الذي طبعته الصفحة. ومؤشر المحادثات يحتفظ بالترتيب الذي صدر به، لذا أرسل معه المرشّحات نفسها.
• —يقرأ --all كل صفحة ويتوقف --max <n> بعد هذا العدد. وعند التمرير عبر أنبوب أو مع --ndjson يطبع كائن JSON واحدًا في كل سطر، ومع --json مستند { items, hasMore, nextCursor } واحدًا.
• —قد تكون hasMore صحيحة في صفحة يتبيّن أنها الأخيرة، فيعيد الاستدعاء التالي صفرًا من العناصر. والمحادثة التي يصلها بريد جديد أثناء تصفحك تتقدم على المؤشر ولا تعيدها الصفحات اللاحقة، وكذلك المسودة المحفوظة أثناء تصفحك.
• —تطلب threads trash وdrafts delete وlabels delete منك التأكيد. ومن دون إشراف، مع --json أو --no-input أو دون طرفية، تتوقف برمز الخروج 2 ولا تغيّر شيئًا ما لم تمرّر --yes.
• —يطبع --dry-run الطلب الذي كان الأمر سيرسله، مع حجب بيانات الاعتماد، ويخرج بالرمز 0 دون إرساله أو طلب التأكيد. ومع --json يطبع { dryRun, request }.

يأخذ --data الجسم كله بصيغة JSON، مضمّنًا، أو من ملف عبر @path، أو من stdin عبر -، وأي خيار تمرّره إلى جانبه يتجاوز مفتاحه.

قيمة الخيار الفارغة خطأ استخدام، لذا فالحقل الذي تمسحه قيمة فارغة يمر عبر --data بدلًا من ذلك. ويمسح --label-color null لون التسمية.

openemail drafts update draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --data '{"from":""}'openemail drafts update draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --data '{"threadId":""}'openemail drafts update draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --data '{"to":[]}'openemail drafts create --data @draft.json --subject "Overrides the file"

الأول يحفظ المسودة دون مرسل، والثاني يفصلها عن المحادثة التي كانت ترد عليها، والثالث يمسح مستلميها.

openemail threads --helpopenemail threads list --helpopenemail drafts create --help --json

يعرض openemail <namespace> <verb> --help كل وسيط وخيار بنوعه، والنطاقات التي يحتاجها الاستدعاء، وطريقته ومساره، وما يعيده، والملاحظات من مرجع API. أضف --json لتحصل على المساعدة نفسها في صورة بيانات.