ربط وكلاء الذكاء الاصطناعي عبر MCP

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

في صفحة موافقة OAuth اختر القراءة فقط أو صلاحيات فردية. الإرسال منفصل عن تعديل الرسائل وحذفها. تشمل القراءة جهات الاتصال والتقويمات والقوالب والمرسلين المحظورين، وتُضمّن صلاحيات الحساب والبحث عن الصناديق اللازمة تلقائيًا. لاتصال White Label استخدم عنوان MCP في لوحة علامتك التجارية.

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

الاتصال من دليل Claude

تم نشر TrekMail كموصل Community في دليل Claude.

افتح TrekMail في Claude، واختر Connect، وسجّل الدخول إلى TrekMail ووافق على الأذونات التي تحتاجها. لا تحتاج إلى رمز API أو عنوان خادم مخصص.

إذا كانت مساحة عمل Claude تقيّد الموصلات، فاطلب من المسؤول تفعيل TrekMail. يمكنك إلغاء الوصول في TrekMail من وكلاء الذكاء الاصطناعي وواجهة API، الرموز، التطبيقات المتصلة.

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

الإجراءات المتاحة: تنطبق خطتك ودور العضو والصلاحيات المعتمدة على كل اتصال. يشمل المرجع أدناه أيضًا API العام وMCP المحلي. في اتصالات الدليل، يفتح إعداد كلمات المرور وبيانات الاعتماد صفحة لوحة موثّقة عبر أداة get_*_setup_link؛ لا ترسل أسرارًا في المحادثة. في ملفات الاتصال عبر دليل ChatGPT/OpenAI وClaude، يعيد إنشاء كلمة مرور لتطبيق بريد أو استبدالها رابطًا آمنًا إلى لوحة التحكم بدلًا من السر. تتم المشتريات وتغييرات الاشتراك في اللوحة.

ChatGPT: إلى أن يتوفر التثبيت من الدليل العام، استخدم الاتصال المخصص في الدليل الرسمي. فعّل Developer mode وأضف عنوان MCP من لوحتك في Plugins وأكمل المصادقة، ثم ثبّت الملحق الشخصي واستخدمه في محادثة Work. ستُضاف تعليمات التثبيت العام بعد النشر.

الطلب الأول وحل المشكلات

• اعرض نطاقاتي.
• اعرض الملفات في Drive الخاص بي.

إذا حظر Claude الموصل، فاطلب من مسؤول مساحة العمل تفعيله. ألغيت تسجيل الدخول أو سحبت الوصول؟ افتح خطوات الاتصال مجددًا لإعادة الربط.

طرق اتصال أخرى

يتيح خادم MCP من TrekMail لعملاء الذكاء الاصطناعي المتوافقين إدارة بنية بريدك الإلكتروني بلغة طبيعية. يشمل الكتالوج النطاقات وصناديق البريد والعلامة التجارية والفرق في White Label وDrive والبريد والتقويم وعمليات النقل والدعم والفوترة والخدمات المرتبطة عبر واجهة TrekMail API نفسها.

لا يتم تحميل الكتالوج الكامل في كل محادثة. تنشئ TrekMail قائمة tools/list من بيانات الاعتماد النشطة: تُحذف الأدوات الواقعة خارج نطاقاتها، وكذلك الأدوات المستبعدة بمجموعة أدوات محددة أو وضع القراءة فقط أو حدود النقل أو إعداد أمان محلي. لذلك تعرض بيانات اعتماد البريد ذات النطاق المحدود قائمة موجزة من أدوات البريد. كما أن بيانات الاعتماد المقصورة على بعض النطاقات لا تحصل على update_account وset_client_limit وremove_client_limit، والمقصورة على بعض الصناديق لا تحصل على update_account وdrive_folder_stop_sharing، لأن API سترفض هذه الأدوات في كل الأحوال.

اختر طريقة الاتصال

تستخدم المسارات 1-3 بروتوكول OAuth 2.1: عند الاتصال لأول مرة، يفتح المتصفح صفحة موافقة TrekMail، فتراجع الأذونات المطلوبة ويحصل العميل على رمز محدود بحسابك. لا يُنسخ أي رمز tm_live_ طويل الأجل إلى العميل. يمكنك إلغاء أي اتصال في أي وقت من وكلاء الذكاء الاصطناعي وAPI، الرموز، التطبيقات المتصلة.

ما الذي تحصل عليه

• مجموعة أدوات خاصة بالاتصال تتم تصفيتها قبل التسجيل وفقا لأذونات الاتصال الحالي وإعدادات أمانه.
• OAuth 2.1 + تسجيل ديناميكي للعميل: يسجل عميل الذكاء الاصطناعي نفسه، ويرشدك خلال صفحة موافقة في المتصفح، ويحصل على رمز محدد النطاق. لا حاجة إلى نسخ رموز طويلة الأجل ولصقها في مسارات الويب أو سطح المكتب أو CLI.
• بنية برمزين: رمز عمليات منفصل للبنية التحتية ورمز رسائل لعمليات بريد الويب الكاملة. عند الاتصال عبر OAuth، يتم إصدار رموز الرسائل تلقائيا لكل صندوق بريد عند الحاجة.
• تكرار آمن تلقائي للعمليات التي تتطلبه، حتى لا تعيد المحاولة تنفيذ العملية نفسها.
• حذف بخطوتين: يتطلب حذف صندوق البريد نية صريحة وتأكيدا، ثم ينقله إلى المحذوفة مؤخرا لاستعادته.
• ضوابط أمان للاستضافة الذاتية: يستطيع مسؤول يشغل خادم MCP stdio الخاص به فرض الموافقة على إجراءات الحذف والإرسال والنقل.
• سجل تدقيق كامل: تُسجل كل عملية API وMCP مع الاحتفاظ بها لمدة 90 يوما.

قبل البدء

• يمكن ربط الوكلاء في جميع الخطط.
  • Nano: أدوات التحقق من البريد الإلكتروني. تؤدي إضافة مساحة Drive أيضا إلى منح الوكيل إمكانات Drive التي يحق للحساب استخدامها، بما فيها التصفح والرفع والمشاركة والاستعادة والحذف النهائي.
  • Starter: وصول كامل إلى Drive وأداة التحقق من البريد، ووصول للقراءة فقط في بقية المجالات (النطاقات وصناديق البريد وعمليات النقل والتذاكر وغيرها). استخدم لوحة التحكم لإجراءات الكتابة التي لا تتيحها Starter عبر API، مثل إنشاء عمليات النقل أو الرد على التذاكر أو تغيير الرد التلقائي.
  • Pro / Agency: وصول كامل للقراءة والكتابة في جميع العائلات.
  • تجربة White Label أو الإضافة: تضيف أدوات العلامة التجارية والعملاء/الفريق والنشاط ما دام الاستحقاق فعالا. بدونها، تُحذف هذه المخططات. خلال مهلة الإلغاء، يحصل المالك وحده على أدوات القراءة.
• هل هذه أول مرة؟ يرشدك زر بدء الجولة في صفحة وكلاء الذكاء الاصطناعي وAPI خلال ربط وكيل والخطوات الخاصة بكل عميل والرموز اليدوية والتطبيقات المتصلة وسجل التدقيق.
• في مسارات OAuth ‏(1، 2، 3) لا تحتاج إلى إنشاء رمز يدويا. ينشئه العميل عبر مسار تفويض المتصفح. في مسار stdio المستضاف ذاتيا (4)، أنشئ أولا رمز tm_live_ في لوحة التحكم.

1. عميل MCP بعيد (موصى به)

استخدم هذا المسار عندما يدعم عميل الذكاء الاصطناعي خوادم MCP البعيدة وتفويض المتصفح.

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

1. افتح إعدادات MCP أو عمليات التكامل أو الموصلات في عميلك.
2. اختر إضافة خادم MCP بعيد أو إضافة موصل مخصص. تختلف التسمية الدقيقة حسب العميل.
3. أدخل:
   • الاسم: TrekMail
   • عنوان خادم MCP البعيد: https://trekmail.net/mcp
4. أكد الاتصال. يفتح المتصفح صفحة تفويض TrekMail.
5. سجل الدخول، وراجع الأذونات المطلوبة، ووافق على الوصول. ارجع إلى العميل عندما يؤكد المتصفح الاتصال.

يصدر التفويض الأول رمزا محدود المدة. تجدده البرامج المتوافقة تلقائيا. لقطع الاتصال، استخدم إجراء القطع في العميل أو ألغ التطبيق من قسم الرموز، التطبيقات المتصلة في TrekMail.

2. عميل CLI أو سطح المكتب

للعميل الذي يقبل أمر stdio، استخدم الجسر المحايد التالي:

npx -y mcp-remote https://trekmail.net/mcp

اضبط هذا الأمر كخادم MCP في عميلك. يفتح الاتصال الأول متصفحك لإجراء التفويض.

توفر بعض البرامج أيضا أمرا خاصا لإضافة خادم MCP بعيد. هذا صالح بالقدر نفسه؛ استخدم https://trekmail.net/mcp عنوانا للخادم واتبع تعليمات العميل.

مثال خاص بالعميل: Claude Code

claude mcp add trekmail https://trekmail.net/mcp -t http

مثال خاص بالعميل: Claude Desktop

عدل ملف الإعدادات (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json) وأضف:

{
  "mcpServers": {
    "trekmail": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://trekmail.net/mcp"]
    }
  }
}

أعد تشغيل Claude Desktop. عند بدء الجسر المحلي، اتبع طلب التفويض في المتصفح.

مثال خاص بالعميل: Cursor

اضبط Cursor باستخدام ملف JSON:

{
  "mcpServers": {
    "trekmail": {
      "url": "https://trekmail.net/mcp"
    }
  }
}

مثال خاص بالعميل: Windsurf

في Cascade، افتح …، Open MCP config file وأضف الإدخال أدناه. هذا إعداد Cascade؛ وقد تستخدم الوكلاء الأخرى ملفًا مختلفًا.

{
  "mcpServers": {
    "trekmail": {
      "serverUrl": "https://trekmail.net/mcp"
    }
  }
}

احفظ الملف وأعد تشغيل العميل ليقرأ التغيير. يفتح الاتصال الأول متصفحك للموافقة على الوصول.

3. mcp-remote ‏(CLI)

يعد mcp-remote مفيدا للاختبار أو لعملاء MCP غير التابعين لـAnthropic الذين لا يدعمون خوادم OAuth البعيدة مباشرة بعد. وهو جسر Node صغير من stdio إلى HTTP بعيد.

npx -y mcp-remote https://trekmail.net/mcp

يفتح التشغيل الأول متصفحك من أجل OAuth. بعد ذلك يُخزن الرمز مؤقتا تحت ~/.mcp-auth/ ويُستخدم تلقائيا.

يمكنك توصيله بأي عميل MCP stdio من خلال توجيهه إلى أمر mcp-remote بدلا من نقطة إدخال Node محلية.

4. استضافة stdio ذاتيا (Claude Desktop / Docker / npm)

إذا أردت رموز tm_live_ ثابتة بدلا من OAuth، مثل الخوادم غير المراقبة أو نسخ TrekMail الخاصة أو النشر في حاوية، فاستنسخ حزمة MCP stdio وشغلها على مضيفك.

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

تثبيت خادم MCP

git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
npm install
npm run build

Claude Desktop ‏(stdio)

أضف ما يلي إلى ملف إعداد MCP الخاص بـClaude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "trekmail": {
      "command": "node",
      "args": ["./trekmail-mcp/build/index.js"],
      "env": {
        "TREKMAIL_BASE_URL": "https://trekmail.net",
        "TREKMAIL_API_TOKEN": "tm_live_your_token",
        "TREKMAIL_MESSAGE_TOKEN": "tm_msg_your_token",
        "TREKMAIL_ALLOW_SENDING": "false",
        "TREKMAIL_ALLOW_MIGRATION": "false"
      }
    }
  }
}

حدث مسار args ليشير إلى موضع استنساخ المستودع. استبدل الرموز برموزك. يمكنك حذف TREKMAIL_MESSAGE_TOKEN إذا كنت تحتاج إلى أدوات البنية التحتية فقط، أو حذف TREKMAIL_API_TOKEN إذا كنت تحتاج إلى أدوات الرسائل فقط. يلزم رمز واحد على الأقل.

Claude Code ‏(stdio)

أضف ما يلي إلى إعدادات MCP في Claude Code ‏(.claude/settings.json أو إعداد على مستوى المشروع):

{
  "mcpServers": {
    "trekmail": {
      "command": "node",
      "args": ["./trekmail-mcp/build/index.js"],
      "env": {
        "TREKMAIL_BASE_URL": "https://trekmail.net",
        "TREKMAIL_API_TOKEN": "tm_live_your_token",
        "TREKMAIL_MESSAGE_TOKEN": "tm_msg_your_token",
        "TREKMAIL_ALLOW_SENDING": "false",
        "TREKMAIL_ALLOW_MIGRATION": "false"
      }
    }
  }
}

Docker

إذا كنت تفضل Docker، فأنشئ الصورة من المستودع وشغلها:

git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
docker build -t trekmail-mcp .

docker run -i \
  -e TREKMAIL_BASE_URL=https://trekmail.net \
  -e TREKMAIL_API_TOKEN=tm_live_your_token \
  -e TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
  -e TREKMAIL_ALLOW_SENDING=false \
  -e TREKMAIL_ALLOW_MIGRATION=false \
  trekmail-mcp

npm محلي (للتطوير)

git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
npm install && npm run build

TREKMAIL_BASE_URL=https://trekmail.net \
TREKMAIL_API_TOKEN=tm_live_your_token \
TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
TREKMAIL_ALLOW_SENDING=false \
TREKMAIL_ALLOW_MIGRATION=false \
npm start

متغيرات بيئة stdio

تنطبق هذه الضوابط فقط على عملية MCP stdio المستضافة ذاتيا التي تشغلها. وهي لا تفعل ميزة في منتج TrekMail أو تعطلها.

أدوات Drive للوكلاء

باستخدام رمز عمليات يتضمن نطاقات Drive، يوفر خادم MCP أدوات للمساحات والاستخدام والتصفح والتحميلات والملفات والمجلدات والمهملات والعمليات المجمعة وروابط المشاركة العامة وإدارة كلمات مرور أجهزة المزامنة وحالة Drive Add-on. يرى اتصالك الأدوات التي تسمح بها نطاقاته.

للوكيل المخصص لـDrive، اضبط TREKMAIL_API_TOKEN وامنح فقط النطاقات التي يحتاجها سير العمل. إذا شغلت stdio مستضافا ذاتيا، فاترك الإجراءات المدمرة معطلة ما لم يكن الوكيل ينفذ مهمة مراجعة للحذف النهائي أو إفراغ المهملات. شراء Drive Add-on وتغيير حجمه وإلغاؤه ليست أدوات MCP؛ يمكن للوكلاء قراءة حالة الإضافة وأسعارها، لكن تغييرات الفوترة تبقى في لوحة التحكم.

راجع نظرة عامة على أدوات Drive في MCP وربط وكلاء الذكاء الاصطناعي بخدمة TrekMail Drive.

الأدوات المتاحة

يعرض خادم MCP هذه الأدوات للوكلاء المتصلين. تُسجل الأدوات بشكل مشروط بناء على الرموز المقدمة.

أما الأدوات التي يستطيع الوكيل رؤيتها فعليا فتحددها أربعة أمور، تُطبق كلها قبل استجابة tools/list:

1. نطاقات رمزك. لا تُسجل أبدا أداة لا يحمل رمزك الصلاحية اللازمة لها.
2. ضوابط أمان stdio المحلية. عند تشغيل خادم stdio المستضاف ذاتيا، يستطيع المسؤول أن يشترط الموافقة على إجراءات الكتابة أو الإرسال أو النقل. أما MCP المستضاف فيستخدم النطاقات التي تمت الموافقة عليها أثناء OAuth.
3. TREKMAIL_READ_ONLY=true، الذي يحذف كل أدوات الكتابة بصرف النظر عن النطاقات والعلامات.
4. قصر الاتصال على بعض النطاقات أو الصناديق. الرمز أو الموصل المقصور على بعض النطاقات لا يحصل أبدا على update_account وset_client_limit وremove_client_limit، والمقصور على بعض الصناديق لا يحصل أبدا على update_account وdrive_folder_stop_sharing. وترفض API هذه الأدوات لمثل هذا الاتصال في كل الأحوال.

وبذلك يمكن تقييد اتصال مستضاف ذاتيا عمدا حتى عندما يملك رمزه نطاقات أوسع. يظل MCP المستضاف مقيدا بالأذونات التي تمت الموافقة عليها أثناء OAuth.

أدوات النطاقات (رمز العمليات)

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

أدوات White Label (رمز العمليات)

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

يستطيع الوكيل تنفيذ إعداد العلامة التجارية من البداية إلى النهاية: يضبط العلامة وينسخ dns_records المرجعة وينشرها باستخدام apply_cloudflare_dns، ثم يتحقق ويفحص الحالة. تُقيد الاستدعاءات التي تغير الوصول بعضوية المستدعي الفعلية وحدود نطاقه حتى عندما يطلب الرمز نطاقات أوسع. ولا يغيّر حدود تخزين العملاء إلا اتصال يصل إلى كل نطاقات الحساب؛ راجع حدّ تخزين خاص لكل عميل من عملائك. راجع دليل API وMCP لعلامة White Label التجارية وإدارة فرق White Label باستخدام API وMCP.

أدوات DNS (رمز العمليات)

أدوات صناديق البريد (رمز العمليات)

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

أدوات صندوق البريد المشترك (رمز العمليات)

الصندوق المشترك هو وارد فريق (⁨support@⁩، ⁨sales@⁩) بلا تسجيل دخول مباشر أو كلمة مرور مشتركة. قراءة (can_read) يفتح الوارد ومجلدات IMAP المشتركة عند توفرها. إرسال باسم (can_send) يسمح بالإرسال من عنوانه. لكل عضو أذوناته، ولا توجد أدوار للأعضاء. عند تفعيل الوصول للإرسال فقط، تسمح القيمتان can_read=false وcan_send=true بالإرسال من بريد الويب أو تطبيق البريد الخاص بالشخص دون قراءة وارد الفريق. لا تدعم Message API الإرسال بهذا العنوان عند امتلاك صلاحية الإرسال فقط.

قد يعيد تغيير الأذونات 422 no_access_left إذا كان سيوقف الإذنين، أو 422 send_only_disabled إذا كان التغيير المطلوب في صلاحية قراءة غير متاح، أو 422 last_reader إذا كان آخر قارئ نشط سيفقد الوصول. استخدم إزالة لإنهاء الوصول كله، وامنح عضوا نشطا آخر صلاحية قراءة قبل إزالة آخر قارئ. تعيد كل هذه الأخطاء أيضًا shared_mailbox_id، وmember_id للعضو الموجود، وhint يذكر الطلب الذي يصلح المشكلة.

دورة حياة صندوق البريد المشترك (رمز العمليات)

تؤدي العودة إلى صندوق عادي إلى إزالة جميع الأعضاء. حدد كلمة مرور جديدة لبريد الويب، ثم أنشئ كلمات مرور تطبيقات لتطبيقات البريد في علامة الأمان.

تغيّر أدوات دورة الحياة الثلاث وأدوات كتابة الأعضاء الثلاث الوصول. يستطيع مسؤول stdio مستضاف محليا أن يشترط TREKMAIL_ALLOW_DESTRUCTIVE=true قبل إتاحتها؛ أما list_shared_mailbox_members فهي للقراءة فقط ومتاحة دائما.

بعد الإنشاء أو التحويل أو تغيير العضوية، اطلب get_mail_client_setup بمعرف صندوق العضو العادي. تعرض shared_mailboxes.items[] المجلدات لمن لديهم قراءة. انتظر native_access_ready=true وتحقق من send_as_ready قبل إعداد القراءة والإرسال. لا يحفظ SMTP نسخة في المرسلة؛ يختار التطبيق مجلدها. delegated_send_addresses قائمة منفصلة بعناوين المرسل المتاحة للفريق في حقل من، وليست مجلدات أو ضمانا لجاهزية الإرسال. سجل الدخول بعنوان العضو وكلمة مرور تطبيق، واستخدم الخوادم التي يعيدها الإعداد، بما في ذلك White Label. يعني الخطأ القابل لإعادة المحاولة native_access_sync_failed أن الحالة السابقة بقيت كما هي.

أدوات Sieve (رمز العمليات)

أدوات الحذف (رمز العمليات)

أدوات النقل (رمز العمليات)

أدوات التذاكر (رمز العمليات)

أدوات SMTP / توجيه النطاق (رمز العمليات)

يُضبط SMTP لكل نطاق: يشير كل نطاق إلى الإرسال المُدار على المنصة أو إلى ملف تعريف SMTP محفوظ (مزودك الخاص، قابل لإعادة الاستخدام عبر النطاقات)، ويحدد إعداد افتراضي واحد على مستوى الحساب ما تبدأ به النطاقات الجديدة.

تغيّر أدوات الكتابة والاختبار أعلاه الإعدادات أو تجري اختبار اتصال. يستطيع مسؤول stdio مستضاف محليا أن يشترط TREKMAIL_ALLOW_DESTRUCTIVE=true قبل إتاحتها؛ أما get_domain_smtp وlist_domain_smtp_profiles وget_domain_smtp_test_status وget_account_smtp_default فهي للقراءة فقط ومتاحة دائما.

أدوات SMTP القديمة (مهملة)

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

أدوات مقاييس الرسائل المزعجة (رمز العمليات)

أدوات الحساب (رمز العمليات)

إدارة رموز الرسائل (رمز العمليات)

أدوات الرسائل (رمز الرسائل)

يفتح رمز الرسائل 64 أداة تغطي واجهة البريد الإلكتروني بالكامل، بما فيها الحسابات الخارجية المتصلة. تُنظم الأدوات حسب مجال الميزة.

يحدد OAuth المستضاف وstdio المحلي صندوق البريد بطرق مختلفة. في HTTP MCP المستضاف، يتضمن مخطط كل أداة رسائل حقلا مطلوبا هو mailbox_id؛ ويستخدمه الخادم لإصدار رمز قصير العمر لصندوق البريد ذاك. في stdio MCP المحلي، يكون TREKMAIL_MESSAGE_TOKEN مرتبطا بالفعل بصندوق بريد واحد، لذلك لا تقبل الأدوات نفسها mailbox_id. صندوق الوارد المتصل هو مستوى ثان من الاختيار: مرر external_account_id بالإضافة إلى mailbox_id في MCP المستضاف، أو بالإضافة إلى رمز الرسائل المرتبط في stdio.

تدير سبع من أدوات الرسائل البالغ عددها 64 الحسابات المتصلة، وتدير خمس منها هويات من وسياسة الرد. استخدم كلتا المجموعتين لسير عمل شبيه بـGmail يقرأ فيه الوكيل صندوق Gmail متصلا، لكنه يرسل من عنوان عمل مصرح به عبر مسار نطاق أو ملف تعريف SMTP محفوظ. راجع عناوين إرسال باسم عبر API وMCP.

الرسائل الأساسية

تعود send_message بمجرد قبول الرسالة وقبل إرسالها فعليا، لذا تأكد من خروجها عبر get_message_delivery؛ ويذكر الخطأ sending_limit_exceeded الحد الذي تم بلوغه وموعد تجدده (resets_at)، ويجب ألا يعيد الوكيل المحاولة قبل ذلك. تعمل get_message_delivery مع أي رمز رسائل لصندوق البريد نفسه، لا مع الرمز الذي أرسل الرسالة فقط، لذا تستطيع الرموز قصيرة العمر في MCP المستضاف، أو رمز مجدد، التحقق من عمليات الإرسال السابقة؛ ويعيد request_id غير معروف الخطأ 404.

يبين الحقل remaining_today في get_mailbox_sending_limits عدد المستلمين الإضافيين الذين يمكن لصندوق البريد هذا الإرسال إليهم اليوم. عندما يكون أدنى حد هو المجموع اليومي للحساب، تكون قيمة limit_today هي null، وكذلك remaining_today إلى أن ينفد ذلك المجموع (فتصبح 0). ويقرأ رمز العمليات مجموع الحساب عبر get_sending_limits.

إذا كان لصندوق البريد CC افتراضي أو BCC افتراضي مضبوط في الإعدادات، الملف الشخصي، فيُضاف إلى ما ترسله send_message وschedule_message تماما كما يحدث مع البريد المكتوب في تطبيق الويب، ولا يُضاف العنوان الموجود أصلا في الرسالة مرتين. مرر apply_default_recipients: false لتعطيله في رسالة واحدة. لا ينطبق ذلك على البريد المرسل عبر عميل بريد على سطح المكتب أو الهاتف من خلال SMTP، إذ لا يمر أبدا عبر API.

المجلدات

المرفقات

المسودات

تعيد كلتا الأداتين uid وuidvalidity للمسودة. احتفظ بهما معا: تتطلب update_draft الحقبة حتى لا يحذف UID قديم أُعيد استخدامه رسالة مختلفة بعد إعادة إنشاء مجلد المسودات. ينبغي أولا فتح المسودة التي عُثر عليها باستخدام list_messages عبر read_message، التي تعيد uidvalidity الحالية لها. يعيد التحديث زوجا جديدا ويتوقف UID القديم عن العمل. في خادم لا يدعم UIDPLUS، قد تكون القيمتان null رغم حفظ مسودة جديدة؛ حدّث المسودات وافتح المسودة قبل تحديثها.

تقبل الأداتان أيضا idempotency_key اختياريا. إذا تركته فارغا، يُعامل كل استدعاء كاستدعاء جديد، ولذلك يؤدي حفظ المسودة نفسها مرتين إلى إنشاء مسودتين. مرر المفتاح نفسه عند إعادة محاولة استدعاء ربما نُفذ بالفعل، وستحصل على النتيجة الأولى بدلا من نسخة مكررة.

الإرسال المجدول

جهات الاتصال

مجموعات جهات الاتصال

التقويم

أدوات مساعدة للإنشاء

تجهز هذه الأدوات بيانات الرد أو إعادة التوجيه. ولا ترسل أي شيء. مرر البيانات المرجعة مباشرة إلى send_message أو save_draft.

الهويات (عناوين الإرسال)

ترسل Message API وأدوات الرسائل من الوارد المشترك فقط مع قراءة وإرسال باسم، باستخدام shared_mailbox_id ورمز العضو. يعيد list_identities العناوين التي تدعمها هذه API فقط. عناوين الفريق التي تظهر في بريد الشخص على الويب لا تظهر كهويات API ولا تقبلها، ولا يمكن تغييرها أو حذفها بهذه الأدوات.

القوالب

المرسلون المحظورون

أدوات التحقق من البريد الإلكتروني (رمز العمليات)

تتوفر أدوات التحقق من البريد الإلكتروني في كل الخطط، بما فيها Nano. والقيد الوحيد هو رصيد اعتماداتك.

أدوات Cloudflare (رمز العمليات)

تتوفر أدوات Cloudflare في خطتي Pro وAgency.

ضوابط الأمان لخدمة stdio المستضافة ذاتيا

عندما تشغل خادم stdio MCP بنفسك، يتحكم TREKMAIL_ALLOW_DESTRUCTIVE في سماح العملية المحلية بالحذف وإجراءات الكتابة الأخرى. اضبطه على true فقط إذا كنت تثق في قدرة الوكيل على التعامل مع حذف صناديق البريد. لا يغير هذا الإعداد توفر الميزات في TrekMail المستضافة.

حتى مع تمكين العمليات المدمرة، يتطلب الحذف دائما خطوتين ويجب على الوكيل ضبط confirm: true صراحة. راجع حواجز الأمان ونوايا الحذف للتفاصيل.

بوابات أمان الإرسال

لأداتي send_message وschedule_message بوابتان مستقلتان للأمان يجب اجتيازهما معا:

1. بوابة البيئة: يجب ضبط TREKMAIL_ALLOW_SENDING=true عند تشغيل خادم MCP.
2. بوابة كل استدعاء: يجب أن يمرر الوكيل confirm_send=true كمعامل في كل استدعاء.

يمنع تصميم البوابتين إرسال البريد الإلكتروني عرضا من عملية مستضافة ذاتيا. اضبط TREKMAIL_ALLOW_SENDING=false عندما ينبغي لوكيلك قراءة الرسائل فقط. تعمل list_scheduled من دون هذا الضابط؛ فهو ينطبق فقط على إنشاء الرسائل المجدولة أو إرسالها.

بوابات أمان النقل

لأدوات كتابة النقل (start_migration وretry_migration وdelete_migration وdelete_bulk_migration وupdate_bulk_migration_job_password وtest_migration_connection وpreview_bulk_migration وstart_bulk_migration وretry_bulk_migration) بوابتان مستقلتان للأمان:

1. بوابة البيئة: يجب ضبط TREKMAIL_ALLOW_MIGRATION=true عند تشغيل خادم MCP.
2. بوابة كل استدعاء: تتطلب كل أداة معامل التأكيد الخاص بها (confirm_start=true أو confirm_retry=true أو confirm_delete=true).

تتوفر cancel_migration وcancel_bulk_migration وresume_bulk_migration دائما بصرف النظر عن ضابط البيئة المستضافة ذاتيا لأنها عمليات أمان أو استئناف. لكنها تظل تتطلب معاملات تأكيد لكل استدعاء.

تعمل أدوات النقل للقراءة فقط (list_migrations وget_migration وlist_bulk_migrations وget_bulk_migration) من دون أي بوابات.

حلول سريعة

• يتعذر على الوكيل الاتصال: تحقق من صحة مسار build/index.js ومن أنك شغلت npm run build بعد الاستنساخ.
• أخطاء "رمز bearer مفقود": تحقق من ضبط واحد على الأقل من TREKMAIL_API_TOKEN أو TREKMAIL_MESSAGE_TOKEN.
• تعمل أدوات القراءة فقط لكن تفشل الكتابة: رمزك مرتبط بخطة Starter. تعمل عمليات الكتابة في Drive على Starter (واجهة Drive الكاملة). أما عمليات الكتابة الأخرى أو توفير صناديق البريد أو بدء عمليات النقل أو الرد على التذاكر، فقم بالترقية إلى Pro أو استخدم لوحة التحكم.
• تعيد أدوات الحذف أخطاء في stdio المستضاف ذاتيا: اضبط TREKMAIL_ALLOW_DESTRUCTIVE=true في بيئة عملية MCP تلك. ينطبق ذلك على الحذف وإجراءات الكتابة الأخرى، بما فيها الرسائل والمجلدات وجهات الاتصال والتقويم والهويات والقوالب والمرسلون المحظورون والرسائل المجدولة.
• تعيد أداة إرسال في stdio المستضاف ذاتيا "الإرسال معطل": اضبط TREKMAIL_ALLOW_SENDING=true في بيئة عملية MCP تلك.
• تعيد أداة الإرسال "لم يتم تأكيد الإرسال": يجب أن يمرر الوكيل confirm_send=true في كل استدعاء لـsend_message أو schedule_message.
• تعيد أداة الإرسال sending_limit_exceeded: نفد أحد حدود الإرسال. يذكر الخطأ أي حد هو (dimension) وموعد تجدده (resets_at)؛ لا تعد المحاولة قبل ذلك. إذا كان الحد هو عدد المستلمين في رسالة واحدة، فقسّم الرسالة بدلا من ذلك. تعرض get_mailbox_sending_limits عدد المستلمين الإضافيين الذين يمكن لصندوق البريد الإرسال إليهم اليوم؛ وتكون قيمة remaining_today فيها null ما دام أدنى حد هو المجموع اليومي للحساب ولم ينفد بعد، ويقرأ رمز العمليات ذلك المجموع عبر get_sending_limits. ويشرح مقال حدود إرسال TrekMail حسب خطة البريد كل حد. قد تُرفض رسالة قبلتها send_message بالفعل عند خروجها من قائمة الانتظار؛ وعندها تعرضها get_message_delivery بالحالة failed مع التفاصيل نفسها. يمكن إعادة إرسال رسالة فشل إرسالها (بسبب حد إرسال مثلا) لاحقا بالمحتوى نفسه، إذ لم تعد API تعيد لها استجابة القبول السابقة. أما إعادة محاولة إرسال ما زال معلقا أو تم تسليمه فتحصل على الاستجابة الأصلية كما كانت.
• لا تظهر أدوات الرسائل: تأكد من ضبط TREKMAIL_MESSAGE_TOKEN برمز tm_msg_ صالح.
• تعيد أدوات كتابة النقل في stdio المستضاف ذاتيا أخطاء: اضبط TREKMAIL_ALLOW_MIGRATION=true في بيئة عملية MCP تلك.
• خطأ 503 عند بدء النقل: بلغ الخادم سعته القصوى للنقل. أعد المحاولة بعد بضع دقائق.
• فشل تنزيل المرفق: تُعاد المرفقات بصيغة base64. قد تستغرق المرفقات الكبيرة (حتى 25 MB) بضع ثوان. تعيد download_all_attachments ملف ZIP مرمزا بصيغة base64 يضم كل المرفقات.
• اختفت المسودة بعد التحديث: تحذف update_draft المسودة القديمة وتضيف بديلا، لذلك تحصل المسودة على هوية UID جديدة. استخدم كلا من uid وuidvalidity من الاستجابة لأي خطوة تالية؛ فالزوج الذي مررته لم يعد يحدد البديل.
• تصل نسخة من كل رسالة إلى مكان لم تحدده: يحتوي صندوق البريد على CC افتراضي أو BCC افتراضي مضبوط في الإعدادات، الملف الشخصي. وينطبق ذلك على ما يرسله صندوق البريد هذا، بما فيه الإرسال عبر API. امسحه من هناك، أو مرر apply_default_recipients: false لتعطيله لرسالة واحدة.
• حدث التقويم غير موجود: تقتصر الأحداث على صندوق البريد المحدد. تأكد من إصدار رمز الرسائل لصندوق البريد الصحيح.