إنشاء رموز API وإدارتها في TrekMail

تتحكم رموز API فيما يمكن لتطبيق أو وكيل فعله في حسابك. لكل رمز اسم ونطاقات وقيود نطاقات اختيارية وتاريخ انتهاء.

هل توصل عميل MCP؟ إذا كان يدعم التفويض عبر المتصفح، فأضف https://trekmail.net/mcp كخادم MCP بعيد ووافق على الوصول في المتصفح. عادة لا تحتاج إلى إنشاء رمز أو لصقه. رموز tm_live_ اليدوية مخصصة للبرامج النصية ومهام CI وMCP المستضاف ذاتيا والعملاء الذين لا يدعمون هذا التدفق. راجع توصيل وكلاء الذكاء الاصطناعي (MCP).

قبل البدء

• يمكن لجميع الخطط، ومنها Nano، إنشاء رموز API. تقتصر خطط Nano على نطاقات Email Verifier (verify:read وverify:write).
• تتيح خطط Starter نطاقات البنية الأساسية للقراءة فقط، إضافة إلى نطاقات Drive وEmail Verifier الكاملة. يمكن لـ Starter أيضا إدارة إعادة التوجيه في لوحة المعلومات، لكن كتابة إعادة التوجيه عبر API (mailboxes:forwarding:write) تتطلب Pro أو Agency. تفتح Pro وAgency جميع النطاقات.
• يستطيع المالك إدارة جميع بيانات اعتماد الحساب. لا يستطيع العضو المفوض الذي يملك إذن رموز API إلا إدارة بيانات الاعتماد التي أنشأها ومنح النطاقات والنطاقات الإلكترونية الموجودة أصلا في عضويته.
• نصيحة: انقر على بدء الجولة في صفحة وكلاء الذكاء الاصطناعي وAPI للتعرف سريعا على خيارات الاتصال والرموز والتطبيقات المتصلة وسجل التدقيق.

إنشاء رمز لأتمتة Drive

تستخدم API الخاصة بـ Drive وأدوات MCP رموز العمليات (tm_live_...). حدد فقط نطاقات Drive التي يحتاجها سير العمل:

• تقارير للقراءة فقط: drive:account:read أو drive:mailbox:read أو drive:addon:read.
• أتمتة الرفع: أضف drive:account:write أو drive:mailbox:write.
• روابط التسليم العامة: أضف drive:account:share أو drive:mailbox:share.
• التنظيف الدائم: استخدم drive:account:purge أو drive:mailbox:purge فقط في رمز منفصل يخضع لرقابة صارمة.

لا يتوفر شراء إضافة Drive أو تغيير حجمها أو إلغاؤها عبر رموز API. يمكن للوكلاء قراءة حالة الإضافة وأسعارها باستخدام drive:addon:read، لكن تغييرات الاشتراك تبقى في لوحة المعلومات.

إنشاء رمز لأتمتة White Label

يستخدم White Label خمسة نطاقات لرموز العمليات: branding:read وbranding:write وmembers:read وmembers:write وactivity:read. لا تظهر إلا أثناء امتلاك الحساب وصول White Label. يصنف members:write على أنه خطير لأنه يستطيع إزالة الوصول وإلغاء مفاتيح شخص آخر.

لتكامل الحالة والتدقيق للقراءة فقط، حدد branding:read وmembers:read وactivity:read. أضف branding:write فقط لإعداد العلامة التجارية وDNS. أضف members:write فقط عندما تحتاج الأتمتة إلى دعوة أشخاص أو تعديلهم.

أثناء مهلة الإلغاء، يحتفظ المالك بنطاقات القراءة الثلاثة للاسترداد، بينما تتوقف الكتابة وبيانات اعتماد White Label المفوضة. لا تعيد إعادة التنشيط بيانات اعتماد ملغاة؛ أنشئ أو فوض بيانات جديدة.

إنشاء رمز

1. انتقل إلى وكلاء الذكاء الاصطناعي وAPI ← الرموز.
2. انقر على إنشاء رمز.
3. املأ النموذج:
   • الاسم: تسمية لتعريف الرمز (مثل "وكيل Claude" أو "مسار CI/CD").
   • الانتهاء: اختر 7 أيام أو 30 يوما أو 90 يوما أو تاريخا مخصصا أو بلا انتهاء.
   • النطاقات: حدد العمليات التي يستطيع الرمز تنفيذها. تحدد كل النطاقات المسموح بها افتراضيا.
   • قيد النطاق: اختر "جميع النطاقات" أو نطاقات محددة لتقييد وصول الرمز.
4. انقر على إنشاء رمز.

بعد الإنشاء، يظهر الرمز بنص صريح مرة واحدة. انسخه فورا أو استخدم زر تنزيل لحفظه في ملف .txt.

لا يمكن عرض الرمز مجددا. احفظه بأمان قبل إغلاق التأكيد.

إنشاء رمز رسائل

تتيح رموز الرسائل للوكلاء قراءة البريد وإرساله من صندوق محدد. وهي منفصلة عن رموز العمليات وتنشأ برمجيا عبر API باستخدام رمز العمليات.

لإنشاء رمز رسائل، يستدعي وكيلك:

curl -s -X POST \
  -H "Authorization: Bearer tm_live_your_ops_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-message-token-my-agent" \
  -d '{"name":"my-agent","scopes":["messages:read","messages:send"]}' \
  https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}/message-tokens

اختر أصغر نطاقات يحتاجها سير العمل:

يعاد الرمز بنص صريح (tm_msg_...) مرة واحدة. أضفه إلى إعداد MCP باسم TREKMAIL_MESSAGE_TOKEN.

تتوفر رموز الرسائل في خطتي Pro وAgency. يجب أن يحمل رمز العمليات النطاق mailboxes:message-tokens:manage.

لصندوق Gmail متصل أو صندوق خارجي آخر، استخدم external_account_id. وليرى المستلمون عنوان عمل مفوضا بدلا منه، استخدم أيضا identity_id تعيده endpoint الهويات. راجع عناوين الإرسال باسم عبر API وMCP.

تنسيق الرمز

يستخدم TrekMail بادئتين لتمييز نوعي الرموز:

تخزن أول 8 أحرف بعد البادئة كبادئة ظاهرة في لوحة المعلومات لتسهيل التعرف عليها.

النطاقات

تتحكم النطاقات فيما يستطيع الرمز فعله. تعتمد الخيارات على خطتك:

• Nano: Email Verifier فقط (verify:read وverify:write). تمنح إضافة Drive Storage الحساب أيضا إمكانات Drive API وMCP التي يحق له استخدامها.
• Starter: وصول كامل إلى Drive وEmail Verifier، ووصول للقراءة فقط إلى كل ما سواهما (النطاقات وصناديق البريد وإعادة التوجيه وعوامل تصفية البريد والرد التلقائي وعمليات الترحيل والتذاكر وSMTP وCloudflare). استخدم لوحة المعلومات لإجراءات الكتابة التي لا يتيحها Starter عبر API، مثل إنشاء عمليات الترحيل أو الرد على التذاكر أو تغيير الرد التلقائي.
• Pro وAgency: وصول كامل. قراءة وكتابة وإنشاء وحذف في جميع العائلات، إضافة إلى رموز الرسائل لقراءة البريد وإرساله عبر API.

نطاقات White Label استحقاق للإضافة وليست اختصارا يتجاوز جدول الخطط. لا تقدم إلا عندما يكون White Label نشطا؛ ويحتفظ المالك بوصول استرداد للقراءة فقط أثناء مهلة الإلغاء.

راجع نطاقات API وأذونات الخطط للحصول على مرجع كل نطاق.

قيود النطاقات

يمكن للرموز افتراضيا الوصول إلى جميع النطاقات في حسابك. لتقييد رمز بنطاقات محددة:

1. حدد النطاقات المحددة في قسم قيد النطاق.
2. اختر النطاقات التي ينبغي للرمز الوصول إليها.

يتلقى الرمز المقيد استجابات 404 عند محاولة الوصول إلى موارد في نطاقات أخرى؛ تتصرف API كأن تلك النطاقات غير موجودة.

إلغاء رمز

1. انتقل إلى وكلاء الذكاء الاصطناعي وAPI ← الرموز.
2. ابحث عن الرمز في القائمة.
3. انقر على إلغاء.
4. أكد الإلغاء.

تتوقف الرموز الملغاة فورا. يتلقى أي طلب API يستخدم رمزا ملغى 401 Unauthorized.

الإلغاء دائم ولا يمكن التراجع عنه. أنشئ رمزا جديدا لاستعادة الوصول.

حالة الرمز

للرموز ثلاث حالات:

استخدم عامل تصفية الحالة في صفحة الرموز لعرضها حسب الحالة.

سجل التدقيق

يظهر كل إنشاء وإلغاء لرمز في علامة تبويب سجل التدقيق. تتضمن الأحداث اسم الرمز والإجراء والوقت.

إصلاحات سريعة

• "النطاقات غير متاحة في خطتك": لا تشمل خطتك تلك النطاقات. تقتصر Nano على verify:read وverify:write (أضف Drive Storage للحصول أيضا على نطاقات drive:*). تضيف Starter وصول القراءة إلى جميع عائلات البنية الأساسية مع Drive وEmail Verifier الكاملين. تفتح Pro وAgency الكتابة في كل مكان.
• فقدت الرمز بنصه الصريح: لا يمكن استرداده. ألغ الرمز وأنشئ آخر.
• الرمز يعمل لكنه يعيد 404 لبعض النطاقات: يحتمل أن عليه قيد نطاق. ألغ الرمز وأعد إنشاءه بخيار "جميع النطاقات" أو أضف النطاقات الناقصة إلى القيد.
• نطاق White Label يعيد scope_blocked_by_entitlement: أعد تنشيط White Label، ثم أنشئ أو فوض بيانات اعتماد بالنطاق المطلوب.
• توقف رمز مفوض بعد تغيير الدور: يؤدي تقليل وصول العضو أو تعليقه أو إزالته إلى إلغاء بيانات الاعتماد المتأثرة فورا. أنشئ رمزا جديدا بعد أن يعيد المالك الوصول الصحيح.