المفاتيح والأعضاء والأدوار

تقرر هذه الأوامر من وما الذي يستطيع الوصول إلى مساحة العمل. يدير openemail keys مفاتيح API ويقرأ ما فعله كل منها، ويدير openemail members الأشخاص في مساحة العمل ودعواتهم، ويحدد openemail roles ما يجوز للعضو أو المفتاح فعله. ويصف openemail me المفتاح أو تسجيل الدخول الذي تستدعي به، ويسرد openemail languages اللغات التي يقبلها الإرسال المترجَم. ولا تحتاج صناديق الوارد المؤقتة إلى تسجيل دخول إطلاقًا: openemail temp هو الطريقة اليومية لاستخدام أحدها، وopenemail temp-mail هو كل استدعاء في API التي تقف وراءه. ويصل openemail api إلى أي نقطة نهاية لا تصل إليها الأوامر الأخرى.

• —يأخذ أمر المفتاح معرّف المفتاح، أي الأحرف الست عشرية الـ 24 بعد oe_live_، كما يعرضها keys list. ويأخذ أمر العضو معرّف الحساب، userId في members list، لا عنوان بريد أبدًا. ويأخذ أمر الدور معرّف role_ من roles list، لأن الأدوار لا يُبحث عنها بالاسم.
• —تستجيب مساحات الأسماء أيضًا لـ key وmember وrole وlanguage وtempMail. وتعمل الأسماء البديلة المعتادة للأفعال، مثل ls وshow وnew وedit وrm. وفي members، التي أفعالها add وremove، يقود new وcreate إلى add، ويقود rm وdel وdelete إلى remove.
• —يسرد openemail <command> --help كل وسيط وخيار بنوعه، والنطاق الذي يحتاجه الاستدعاء، وطريقته ومساره، وما يعود. أضف --json لتحصل على الصفحة نفسها في صورة بيانات.

قراءة المفاتيح تحتاج إلى keys:read، وكل تغيير يحتاج إلى keys:manage. ولا يُمنح تسجيل الدخول عبر المتصفح أبدًا keys:write أو keys:manage، لذا يتطلب إنشاء المفاتيح وتغييرها وتدويرها وإبطالها وحذفها مفتاح API يحمل keys:manage، أو تطبيق الويب (openemail open api-keys). وتسجيل الدخول عبر المتصفح مع keys:read لا يقرأ المفاتيح إلا لمالك مساحة العمل، ويُرفض تسجيل دخول العضو بـ 403 owner_only.

• —تطبع keys create وkeys rotate وme rotate سر المفتاح، في token، مرة واحدة، ثم تحذّر CLI من أنه لن يُعرض مرة أخرى. وكل قراءة تعرض maskedKey بدلًا منه.
• —إن أُغفلت القيم، فالمفتاح الجديد يحمل emails:send فقط، ويأخذ دور المفتاح الذي ينشئه ونطاق إرساله وانتهاء صلاحيته. ويحدد --domain-allowlist و--address-allowlist من يجوز له الإرسال باسمه، ويأخذ --expires-in-minutes من 5 إلى 5,256,000، أي عشر سنوات.
• —المفتاح لا ينشئ أبدًا مفتاحًا أوسع منه ولا يصل إليه. يجب أن تقع النطاقات والدور وانتهاء الصلاحية والوضع ونطاق الإرسال كلها داخل المفتاح المستدعي، وإلا رُفض الاستدعاء بـ 403 beyond_caller_authority، وتسمّي param ما كان أوسع مما ينبغي. والمفتاح المقيّد ببعض النطاقات أو العناوين لا يرى إلا المفاتيح الواقعة داخل نطاق إرساله، وأي مفتاح آخر يعطي 404.
• —يستبدل keys update ما ترسله: يأخذ كل من --scopes و--address-allowlist و--domain-allowlist القائمة الجديدة كلها، والخيار الذي تُغفله يبقى كما كان. ويوقف --no-enabled المفتاح، فيُرفض كل استدعاء به بـ inactive_api_key، ويعيده --enabled كما كان تمامًا. وهذا يوقف المفتاح بطريقة يمكن التراجع عنها.
• —keys revoke نهائي: لا يمكن أبدًا إعادة تشغيل المفتاح أو تدويره أو تغييره. ولا يزيل keys delete إلا مفتاحًا مبطَلًا، وأي مفتاح آخر يُرفض بـ 409 not_revoked. ويبقى سجل طلبات المفتاح المحذوف ونشاطه، تحت «مفتاح محذوف».
• —لا نافذة تداخل في keys rotate، فيتوقف السر القديم عن العمل لحظة عودة الجديد. وحين يكون المفتاح هو الذي يستخدمه ملفك الشخصي المحفوظ، تحفظ CLI السر الجديد في ذلك الملف فيظل يعمل. أما المفتاح القادم من OPENEMAIL_API_KEY أو --api-key فلا يمكن حفظه، لذا تطلب منك CLI تخزين الرمز الجديد حيثما كان المفتاح القديم محفوظًا.

يسجل سجل الطلبات كل استدعاء أجراه مفتاح: الطريقة، والمسار، والحالة، ورمز الخطأ، والمدة، وعنوان IP، ووكيل المستخدم، ولا جسم ولا سلسلة استعلام أبدًا. لا يُقتطع منه شيء، فيمتد إلى أول استدعاء للمفتاح، والاستدعاءات التي تجري بتسجيل الدخول عبر المتصفح ليست فيه. ويسجل سجل النشاط كل تغيير على مفتاح، وكل استدعاء قدّم المفتاح ورُفض، بوصفه auth_failed، مع من أجرى كل تغيير في actor.

• —يقرأ list-requests وlist-activity مفتاحًا واحدًا. ويقرأ list-workspace-requests وlist-workspace-activity كل مفتاح تستطيع رؤيته، أو حتى 50 مفتاحًا يسمّيها --key-ids، بما فيها المفاتيح المحذوفة.
• —يُبقي --since و--until فترة ويأخذان وقتًا بصيغة ISO 8601 مثل 2026-09-01T00:00:00Z. ويُبقي --failed-only الاستدعاءات التي أُجيبت بحالة 400 أو أكثر.

openemail me get هو أول أمر تشغّله حين يُرفض استدعاء. لا يحتاج إلى نطاق، لذا يستطيع أي مفتاح أو تسجيل دخول صالح أن يصف نفسه.

• —scopes هي ما يجوز لبيانات الاعتماد فعله الآن: النطاقات التي أُنشئت بها، مقلَّصة بالدور الذي صدرت تحته، تُحسب في كل طلب. وgrantedScopes هي ما أُنشئت به، وroleId يسمّي الدور. والنطاق الموجود في grantedScopes والناقص من scopes أزاله الدور. وهذا هو السبب المعتاد لـ 403 insufficient_scope على مفتاح يبدو أنه يحمل النطاق، والحل هو تغيير الدور لا إنشاء مفتاح آخر.
• —تقول domainAllowlist وaddressAllowlist من يجوز له الإرسال باسمه. وكون الاثنين null يعني أي عنوان تملكه مساحة العمل.
• —مع تسجيل الدخول عبر المتصفح يصف تسجيل الدخول: object هو oauth_token، وclientId يسمّي التطبيق المرتبط الخاص بهذه CLI، وexpiresAt هو موعد انتهاء موافقتك، أو null حين لا تنتهي أبدًا.
• —يجيب me ping بـ ok: true مع تفاصيل النطاق نفسها لكن دون قوائم السماح، وهذا يناسب فحص الصحة. والمفتاح المبطَل أو المنتهي أو الموقوف أو المكتوب خطأً يفشل بـ 401 ورمز الخروج 3.
• —يمنح me rotate المفتاح الذي تستدعي به سرًّا جديدًا. ويحتاج إلى keys:write، الذي لا يحمله تسجيل الدخول عبر المتصفح أبدًا، لذا يحتاج إلى مفتاح API. ويبقى كل شيء آخر في المفتاح، ويتوقف السر القديم فورًا، ويحصل الملف الشخصي المحفوظ على الجديد، كما في keys rotate. وضياع الجواب قد يترك المفتاح بسرّ لم يره أحد، فيحتاج حينها إلى سرّ جديد من تطبيق الويب.
• —يعرض openemail whoami الجواب نفسه منسقًا للبشر.

يطبع openemail languages list جدول اللغات كله في جواب واحد، نحو مئتي صف، مع رمز كل لغة واسمها بالإنجليزية واسمها بلغتها وعلمها وما إذا كانت تُكتب من اليمين إلى اليسار. ويعمل الرمز أو الاسم الإنجليزي أو الاسم بلغتها كلها هدفًا للإرسال المترجَم. ويحتاج إلى تسجيل دخول دون نطاق. ويطبع openemail ai languages الجدول نفسه مع خيار --search، ودون تسجيل دخول يطبع الجدول المضمَّن في CLI.

يحمل العضو شيئين لا يُدمجان أبدًا. دوره يقول ما يجوز له فعله، ومنح العناوين والنطاقات الخاصة به تقول أي بريد يجوز له فعل ذلك به، ولكل منحة وصولها الخاص: member يقرأ ويرسل، وviewer يقرأ فقط. والإرسال يحتاج إلى الاثنين، فالدور الذي فيه emails:send مع منحة viewer على عنوان لا يستطيع الإرسال منه. والنطاق الكامل يغطي كل عنوان عليه، بما فيها العناوين التي تُنشأ لاحقًا.

• —يضع members list مالك مساحة العمل أولًا، معلَّمًا بـ isOwner، لذا استبعد ذلك الصف عند عدّ المقاعد. يحمل المالك كل إذن ولا يمكن دعوته أو تغييره أو إزالته، ولا يمكن كذلك دعوة من هو في مساحة العمل بالفعل مرة أخرى: وكلاهما 422 member_is_owner.
• —الأشخاص الذين يحملون منح عناوين لكنهم لم يُعطوا دورًا قط يعودون مع implied: true، ويُستنتج دورهم من منحهم. ويمنحهم members update دورًا حقيقيًا.
• —يرسل members add دعوة، حتى لمن لديه حساب بالفعل. لا يُمنح شيء حتى يقبل، ثم يُمنح بالضبط الدور والعناوين والنطاقات التي تحملها. ودعوة العنوان نفسه من جديد خلال عشر دقائق تعطي 409 invitation_too_soon، وبعد ذلك تُحدِّث الدعوة المنتظرة بدلًا من إرسال ثانية.
• —يرسل resend-invitation رابطًا جديدًا صالحًا لـ 14 يومًا إضافية ويُحيل القديم إلى التقاعد، وهذا يجدد أيضًا الدعوة المنتهية. ويسحب revoke-invitation دعوة، والدعوة المقبولة بالفعل تعطي 409 invitation_accepted، فأزِل العضو بدلًا من ذلك.
• —يغيّر members update الدور ولا شيء غيره. ويمنح grant-address عنوانًا واحدًا أو يغيّر الوصول إليه، فتشغيله مرة أخرى مع --access آخر يغيّر المنحة بدلًا من إضافة ثانية. ويسترجع revoke-address عنوانًا واحدًا ويترك البقية. وإبطال آخر منحة لعضو مستنتَج يزيله من مساحة العمل.
• —ينهي members remove وصول شخص إلى مساحة العمل، وعضويته وكل منحة له، ويبلّغ في addressesRevoked عن عدد منح العناوين التي ذهبت. ويبقى حسابه والبريد الذي أرسله دون مساس.

الدور سقف أيضًا لمفاتيح API الصادرة تحته. وما يجوز للمفتاح فعله هو نطاقاته الخاصة مقلَّصة بأذونات دوره، تُحسب في كل طلب.

• —يعرض roles list الأدوار المزروعة أولًا، بالترتيب Owner وAdmin وMember وViewer وDeveloper وBilling، ثم الأدوار المخصصة بالاسم. وتضم مساحة العمل حتى 24 دورًا مخصصًا، وبعد ذلك يعطي roles create الرمز 422 role_limit_reached.
• —يخزّن الدور الأذونات التي تقتضيها أذوناته، فـ templates:write يخزّن أيضًا templates:read، وroles:write يجلب roles:read وmembers:read. اقرأ القائمة من الجواب بدلًا من افتراضها.
• —يستبدل roles update --permissions القائمة كلها، لذا اقرأ الدور، وغيّر القائمة، وأرسلها كلها. ويمسح --description null الملاحظة. ويسري التغيير في الاستدعاء التالي لكل عضو ومفتاح يحمل الدور.
• —يمكن إعادة تسمية كل دور عدا Owner وإعادة كتابته وحذفه، بما فيها الأدوار المزروعة، والدور المزروع المحذوف لا يعود. ويجيب دور المالك عن التعديل بـ 409 role_immutable وعن الحذف بـ 409 role_undeletable.
• —ما دام أي عضو أو مفتاح API أو دعوة منتظرة يحمل دورًا، يحتاج roles delete إلى --reassign-to مع الدور الذي يتولاهم، وإلا رُفض بـ 409 role_in_use. والمفاتيح المبطَلة لا تزال تشير إلى دورها، لذا قد يحتاجه دور عدد apiKeys فيه 0. ويبلّغ الجواب عن الأشخاص في reassigned والمفاتيح في keysReassigned.
• —يسرد roles list-permissions المفردات كلها مع تسمية ومجموعة لكل منها. وبعضها، مثل billing:write وworkspace:manage، يعود مع scope: false: يجوز للدور أن يحملها، لكن لا يستطيع ذلك أي مفتاح.

لا يحتاج صندوق الوارد المؤقت إلى حساب ولا إلى تسجيل دخول. يُوصَل إليه برمز صندوقه الخاص، الذي يبدأ بـ oe_inbox_ ويعود مرة واحدة، عند إنشاء الصندوق. استخدم openemail temp في الاستخدام اليومي، وopenemail temp-mail حين تحتاج إلى حقل أو خطوة لا يعرضها temp، مثل التمديدات المتبقية، أو تمديد، أو بايتات مرفق.

• —كلاهما يحفظ الرمز في ~/.openemail/temp-mail.json، الذي لا يقرؤه أحد سواك. يحفظه temp new وtemp-mail create، ويعرض temp list الصناديق المنشأة بأي من الطريقتين، وينساه كلا الحذفين. ويمكن تسمية الصندوق المحفوظ بعنوانه أينما طلب أمر معرّفه.
• —لصندوق وارد لم تنشئه هذه CLI، مرّر الرمز بـ --inbox-token. ودون رمز محفوظ أو ممرَّر، يتوقف الأمر برمز الخروج 3 قبل إرسال أي شيء.
• —يسمّي أمرا الإنشاء خياراتهما بطريقة مختلفة: يأخذ temp new الخيارات --name و--domain و--ttl، ويأخذ temp-mail create الخيارات --local-part و--domain و--ttl-minutes. والجزء المحلي من 3 إلى 32 حرفًا من الحروف أو الأرقام أو النقاط أو الشرطات أو الشرطات السفلية، يبدأ وينتهي بحرف أو رقم، وتُرفض أسماء مثل postmaster. ومدة الإيجار من 1 إلى 1440 دقيقة، و60 افتراضيًا.
• —يستطيع كل عنوان IP إنشاء 6 صناديق في الساعة و30 في اليوم، والتالي يعطي 429 too_many_inboxes، برمز الخروج 8. وتمديد صندوق تملكه بالفعل لا يُحتسب، لذا فإن temp-mail extend هو الجواب عن ذلك الحد.
• —يضيف temp-mail extend حتى ساعة، ولا يتجاوز أبدًا 24 ساعة بعد إنشاء الصندوق، و23 مرة على الأكثر. اقرأ extensionsLeft من الجواب. وعند 0 يصبح 409 extension_limit نهائيًا.
• —يقرأ temp-mail list-messages من 1 إلى 50 رسالة في الصفحة، و50 افتراضيًا، لكل منها snippet نصي حتى 400 حرف كثيرًا ما يحمل رمزًا لمرة واحدة. ولا يُسقط شيء بعد الصفحة، ويمر --all على كل صفحة.
• —قراءة رسالة بـ temp read أو temp-mail get-message أو temp-mail list-attachments تعلّمها كمطّلع عليها. والنص الذي يتجاوز 2 MB يُقتطع، وتقول truncated ذلك، والمرفق الذي يتجاوز 8 MB لم يُحتفظ به قط، فتكون content الخاصة به null.
• —حذف صندوق وارد يحذف بريده فورًا، لكن العنوان يبقى محجوزًا حتى 7 أيام بعد الموعد الذي كان إيجاره سينتهي فيه، وطلبه من جديد قبل ذلك يعطي 409 address_taken.

يرسل openemail api <method> <path> طلبًا واحدًا عبر النقل نفسه الذي يستخدمه كل أمر آخر، لذا ينطبق ملفك الشخصي أو مفتاحك، وتجديد الرمز، ورموز التحقق، والتأكيدات كلها. والمسار وحده يعني GET، ويُطبع جواب JSON منسقًا. وopenemail api /keys/self هو الاستدعاء الذي يقف وراء me get.

• —يأخذ -d و--data الجسم بصيغة JSON مضمّنة، أو من ملف بـ @path، أو من stdin بـ -. ويأخذ -q و--query و-H و--header القيمة key=value ويمكن تكرارها، ويحفظ -o و--out الرد في ملف كما وصل.
• —DELETE، وأي استدعاء كان أمر الموارد سيطلب تأكيده، مثل إبطال مفتاح أو تدويره، يطلب منك التأكيد أولًا، ومن دون إشراف يحتاج إلى --yes.
• —الطلب الفاشل يطبع خطأ API ويخرج بالرمز المطابق.

لا تُسرد مساحة الأسماء security في openemail --help، لأن openemail verify يقودها. وأفعالها step-up-status وbegin-step-up وverify-step-up هي الاستدعاءات التي يجريها verify: يقرأ verify --status الحالة، ويطلب verify رمزًا، ويسألك عنه، ويتحقق منه. وهي موجودة لتسجيل الدخول عبر المتصفح. ومع مفتاح API يُرفض كل منها بـ 400 step_up_not_applicable، ويقول openemail verify إن المفتاح لا يحتاج إلى رمز أبدًا.

openemail keys create --name 'Billing sender' --scopes emails:send \  --domain-allowlist billing.acme.com --expires-in-minutes 129600 --json \  | jq -r .token | openemail login --with-token --profile billingopenemail whoami --profile billing

شغّله بمفتاح API يحمل keys:manage، عبر OPENEMAIL_API_KEY مثلًا. يذهب السر من الجواب مباشرة إلى ملف شخصي جديد، فلا يظهر أبدًا على الشاشة ولا في ملف. ولا يستطيع المفتاح الإرسال إلا من billing.acme.com، وتنتهي صلاحيته بعد 90 يومًا.

openemail keys list --all | jq -r 'select(.status != "active") | [.name, .status, .lastUsedAt] | @tsv'openemail keys list-workspace-requests --failed-only --since 2026-09-26T00:00:00Z --all \  | jq -r '[.createdAt, .keyName, .status, .errorCode, .method, .path] | @tsv'

id=4c1b257a66287fd113bd89d0openemail keys update "$id" --no-enabledopenemail keys list-activity "$id" --since 2026-09-27T00:00:00Z --all | jq -r 'select(.type == "auth_failed") | .createdAt'openemail keys revoke "$id" --reason 'Contractor offboarded' --yesopenemail keys delete "$id" --yes

إيقاف المفتاح أولًا يمكن التراجع عنه بـ --enabled. وكل استدعاء لا يزال يقدّمه يُرفض ويظهر في نشاطه بوصفه auth_failed، وهذا يخبرك بما لا يزال يعتمد عليه. أما الإبطال فلا تراجع عنه، ولا يمكن حذف إلا مفتاح مبطَل.

openemail roles list-permissions --json | jq -r '.[] | [.group, .id, .label] | @tsv'role=$(openemail roles create --name Support --permissions threads:write,emails:send,templates:read \  --description 'Answers help@ and nothing else.' --json | jq -r .id)openemail members add --email [email protected] --role-id "$role" \  --domain-ids 93542ff8-2baa-4f2f-841d-5ceaa074ab0d --access memberopenemail members list-invitations

يعود الدور حاملًا threads:read وemails:read أيضًا، لأن الأذونات التي يسمّيها تقتضيهما. ولا يحصل Sam على الدور والنطاق الكامل إلا بعد أن يقبل. ومع تسجيل الدخول عبر المتصفح، يطلب members add رمز تحقق أولًا.

old=role_8b1f4c2e9a7d3b60e5f1a2c4new=role_2c7e9a1f4b8d3e60c5a7f1b9user=$(openemail members list --all | jq -r 'select(.email == "[email protected]") | .userId')openemail members update "$user" --role-id "$new"openemail roles get "$old" --json | jq '{name, members, apiKeys}'openemail roles delete "$old" --reassign-to "$new" --dry-runopenemail roles delete "$old" --reassign-to "$new" --yes

يُعدّ members وapiKeys حين تسأل، فيبيّنان ما سينقله الحذف. ويطبع التشغيل التجريبي DELETE مع reassignTo في استعلامه دون إرساله. ومع تسجيل الدخول عبر المتصفح، يطلب كل من التحديث والحذف رمز تحقق، لذا شغّل openemail verify أولًا حين يفعل سكربت ذلك.

address=$(openemail temp new --ttl 15)openemail send --from [email protected] --to "$address" --subject 'Delivery check' --text 'Your code is 482913' --yesopenemail temp watch "$address" --first --json | jq -r .snippet | grep -oE '[0-9]{6}'openemail temp delete "$address" --yes

لا يطبع temp new إلا العنوان، فيتسع له متغير صدفة، ويتوقف temp watch --first عند أول رسالة. وجّه نموذج تسجيل إلى العنوان بدلًا من openemail send لتلتقط رمز تأكيده بالطريقة نفسها.

• —تسجيل الدخول أو المفتاح الذي لا يملك النطاق يتوقف برمز الخروج 4، ويسمّي النطاق الناقص ويقول كيف تحصل عليه.
• —تطلب هذه منك التأكيد: keys delete وrotate وrevoke، وme rotate، وroles delete، وmembers remove وrevoke-address وrevoke-invitation، وtemp delete، وtemp-mail delete وdelete-message. والإجابة بلا تخرج بالرمز 10 ولا تغيّر شيئًا. ومن دون إشراف ودون --yes تتوقف برمز الخروج 2 قبل إرسال أي شيء.
• —مع تسجيل الدخول عبر المتصفح، يطلب roles update وroles delete، وmembers add وupdate وremove وgrant-address وrevoke-address، رمز تحقق أيضًا، ما لم يكن تسجيل الدخول هذا قد تحقق من رمز خلال الدقائق الـ 60 الماضية. لا يتخطاه --yes أبدًا، ومن دون إشراف لا أحد يستطيع كتابته، فيتوقف الأمر برمز الخروج 4. شغّل openemail verify أولًا. ولا يُطلب من مفتاح API أبدًا.
• —يطبع --dry-run الطلب الذي كان التغيير سيرسله، مع جسمه، ويخرج بالرمز 0 دون إرساله أو طلب التأكيد منك.
• —تقرأ القائمة صفحة واحدة. يأخذ --limit من 1 إلى 100 ويرسل الخادم 25 حين يُغفل، عدا temp-mail list-messages الذي يأخذ من 1 إلى 50 ويرسل 50. ويأخذ --cursor قيمة nextCursor من الصفحة السابقة. ويقرأ --all كل صفحة، ويتوقف --max <n> بعد هذا العدد من العناصر، ويطبع --ndjson، أو --all في أنبوب، كائن JSON واحدًا في كل سطر. ومع --json تطبع القائمة مستند { items, hasMore, nextCursor } واحدًا.
• —تعيد roles list-permissions وlanguages list وtemp-mail list-domains وtemp-mail list-attachments كل شيء دفعة واحدة، في مصفوفة عادية، دون صفحات.
• —يخرج الرفض برمز حالته: 3 لـ 401، مثل مفتاح مبطَل، و4 لـ 403، مثل beyond_caller_authority أو owner_only، و5 لـ 404، و6 لـ 409، مثل not_revoked أو role_in_use أو invitation_too_soon، و7 لـ 400 أو 422، مثل member_is_owner أو role_limit_reached، و8 لـ 429، مثل too_many_inboxes.
• —التغيير الذي قد يفعل شيئًا مرتين لا يُعاد أبدًا بعد فشل في الشبكة: keys create وrotate، وme rotate، وroles create وdelete، وmembers add وremove وrevoke-address وresend-invitation، وtemp-mail create وextend وdelete وdelete-message. تحقّق قبل أن تشغّل أحدها من جديد. أما القراءات، والتغييرات التي تنتهي إلى النتيجة نفسها مرتين، مثل keys update وkeys revoke وroles update وmembers update وgrant-address، فتُعاد تلقائيًا.