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

افتح TrekMail في Claude، واختر Connect وسجّل الدخول واسمح بالوصول. لا تحتاج إلى إنشاء رمز API. يمكنك مراجعة الصلاحيات أو قطع الاتصال في AI Agents & API → Tokens → Connected apps.

علامتك الخاصة White Label: استخدم عنوان MCP المعروض في لوحة علامتك وسمّ الموصل باسمها. أضفه كـ custom connector؛ صفحة TrekMail العامة تسجّل الدخول عبر TrekMail ولا تحل محل اتصال علامتك.

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

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

قراءة البريد بمفتاح واحد

في خطتي Pro وAgency، اختر قراءة البريد عند إنشاء مفتاح API. الصلاحية الصريحة هي mailboxes:messages:read؛ أما mailboxes:read فتعرض العناوين وبيانات الاتصال فقط. اختيار جميع الصناديق يشمل الحالية والمستقبلية، ويمكن قصر الوصول على نطاقات وصناديق محددة. لا تحصل المفاتيح الحالية على صلاحيات جديدة تلقائيًا.

استخدم مفتاح الحساب مع مسارات GET أدناه. لا يزال الإرسال والحذف والتعديل يتطلب بيانات وصلاحيات رسائل منفصلة. يقبل MCP المستضاف OAuth وليس tm_live_ أو tm_msg_. يوضح خطأ نوع الرمز للوكيل المسار أو طريقة التفويض الصحيحة.

GET /api/v1/mailboxes/{mailbox}/messages
GET /api/v1/mailboxes/{mailbox}/folders
GET /api/v1/mailboxes/{mailbox}/messages/{uid}
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/raw
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/attachments/{index}

اختيار صلاحيات التطبيق وتعديلها

افتح تفاصيل مفتاح API أو التطبيق المتصل، واختر تعديل الوصول، ثم راجع التغييرات وأكدها. يبقى سر مفتاح API نفسه. تقليل الصلاحيات والموارد والمدة يقيّد أيضًا رموز الصناديق الحالية ويلغي الإرسال الذي لم يبدأ. يمكن تقييد اتصالات OAuth الجديدة فورًا؛ وتوسيع الوصول يحتاج موافقة جديدة. تعديل اتصال قديم يفصله ويحفظ الاختيارات لإعادة الاتصال. يمكن لرموز الرسائل فقط فقد صلاحيات أو تقصير مدة الصلاحية.

قبل البدء

• يمكن لجميع الخطط، ومنها 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 وأذونات الخطط للحصول على مرجع كل نطاق.

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

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

• النطاقات المحددة فقط: يصل الرمز إلى النطاقات التي تحددها ولا شيء غيرها. النطاق الذي تضيفه لاحقا يبقى خارج الوصول حتى تعدّل الرمز وتحدده.
• جميع النطاقات (الحالية والمستقبلية) باستثناء…: يصل الرمز إلى كل النطاقات عدا التي تحددها، بما فيها النطاقات المضافة لاحقا. يفيد ذلك في إبعاد وكلائك عن بريد أحد العملاء دون تعديل الرمز كلما أضفت نطاقا.

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

بالنسبة لعضو الفريق المقيد ببعض النطاقات، يعني "باستثناء…" نطاقات هذا العضو مطروحا منها ما يحدده، ولا يشمل النطاقات التي تُضاف إلى الحساب لاحقا. إذا حذفت نطاقا مستثنى ثم أضفته من جديد، فإنه يُعد نطاقا جديدا: استثنه مرة أخرى.

إعادة إنشاء رمز

أعد إنشاء الرمز عندما تحتاج إلى سره مرة أخرى أو عندما يحتمل أن يكون السر قد تسرّب. يحتفظ الرمز باسمه وأذوناته ونطاقاته وصناديق بريده وتاريخ انتهاء صلاحيته وسجل التدقيق الخاص به. يتغير السر فقط.

1. انتقل إلى وكلاء الذكاء الاصطناعي وAPI ← الرموز وافتح التفاصيل الخاصة بالرمز.
2. انقر على إعادة الإنشاء.
3. اختر موعد توقف السر القديم: الآن أو بعد ساعة واحدة أو بعد 24 ساعة أو بعد 3 أيام أو بعد 7 أيام. لا يعمل السر القديم أبدًا بعد انتهاء صلاحية الرمز نفسه.
4. انقر على إعادة الإنشاء وانسخ السر الجديد. يُعرض مرة واحدة فقط، كما في الرمز الجديد.

ما دام السر القديم يعمل، تعرض تفاصيل الرمز موعد توقفه وتتيح إيقافه الآن. استبدل السر في كل تطبيق قبل ذلك: تتلقى الطلبات التي تستمر في استخدام السر القديم بعد ذلك 401 Unauthorized.

تتوقف رموز الرسائل (tm_msg_...) التي أُنشئت بالسر القديم عن العمل في الوقت نفسه. يمكن للتطبيق الذي ينشئ رموز الرسائل بنفسه أن ينشئ رموزًا جديدة بالسر الجديد. إذا احتمل أن يكون السر قد تسرّب، فاختر الآن.

إلغاء رمز

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، ثم أنشئ أو فوض بيانات اعتماد بالنطاق المطلوب.
• توقف رمز مفوض بعد تغيير الدور: يؤدي تقليل وصول العضو أو تعليقه أو إزالته إلى إلغاء بيانات الاعتماد المتأثرة فورا. أنشئ رمزا جديدا بعد أن يعيد المالك الوصول الصحيح.