الحسابات المتصلة عبر API وMCP

تتيح الحسابات المتصلة لصندوق بريد الويب قراءة الرسائل وإرسالها من صناديق بريد خارجية أو Gmail أو Yahoo أو iCloud أو Outlook.com/Microsoft 365 أو أي خادم IMAP. توفر واجهة API للرسائل وأدوات MCP الإمكانية نفسها برمجيا: يمكنك عرض الحسابات المتصلة وإضافتها واختبارها وتعديلها وإزالتها، كما يمكنك توجيه استدعاءات الرسائل المعتادة (العرض والقراءة والإرسال والعلامات والنقل والحذف والمجلدات) إلى حساب متصل بدلا من صندوق البريد الخاص بالرمز المميز.

بعبارة بسيطة: يحدد mailbox_id صندوق بريد TrekMail الذي يجوز للوكيل العمل نيابة عنه، بينما يحدد external_account_id حساب Gmail أو صندوق بريد آخر متصل داخله. لا يمكن استخدام أحدهما مكان الآخر.

الخطط والحدود وحجم الكتالوج

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

قبل أن تبدأ

• الحسابات المتصلة إحدى ميزات بريد الويب وتستخدم واجهة الرمز المميز للرسائل (/api/v1/messages/...). يتم تفويضها برمز مميز للرسائل يحمل النطاقات أدناه، وليس برمز API للوحة التحكم.
• تطبق حدود الخطة على كل صندوق بريد: Starter 5, Pro 10, Agency 30. لا تتضمن خطة Nano الحسابات المتصلة.
• يقتصر كل endpoint على صندوق البريد الخاص بالرمز المميز. لا يمكن للرمز المميز رؤية وإدارة إلا حساباته المتصلة، ولا يمكنه الوصول إلى حسابات صندوق بريد آخر.
• تكون بيانات الاعتماد ورموز OAuth محجوبة دائما في الاستجابات. يمكنك إدخال كلمة مرور أو كلمة مرور تطبيق، ولكن لا يمكنك قراءتها مجددا.
• يتم ربط حسابات Outlook.com وMicrosoft 365 عبر تسجيل الدخول إلى Microsoft (OAuth) في واجهة بريد الويب. تستطيع واجهة API إدارتها واستخدامها بعد ربطها، لكنها لا تنفذ خطوة موافقة Microsoft التفاعلية.

النطاقات

يتطلب توجيه استدعاء رسائل إلى حساب متصل النطاق نفسه الذي يحتاج إليه الاستدعاء أصلا (على سبيل المثال، يتطلب عرض رسائله messages:read، ويتطلب الإرسال messages:send).

إدارة الحسابات المتصلة

المسار الأساسي: /api/v1/messages/external-accounts

إضافة حساب

POST /api/v1/messages/external-accounts
Scope: messages:write

نص الطلب:

استدع أولا POST /external-accounts/detect لملء provider وإعدادات الخادم تلقائيا. يجري استدعاء التخزين اختبار IMAP + SMTP فعليا قبل الحفظ. تعني استجابة 422 مع فئة خطأ (auth أو tls أو network أو transient_throttle) أن بيانات الاعتماد لم تعمل وأنه لم يتم تخزين أي شيء.

توجيه استدعاءات الرسائل إلى حساب متصل

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

GET /api/v1/messages?external_account_id=42&folder=INBOX
Scope: messages:read

POST /api/v1/messages/send
Scope: messages:send
{
  "external_account_id": 42,
  "to": "someone@example.com",
  "subject": "Sent from my connected account",
  "text": "..."
}

يتم الإرسال باستخدام external_account_id وحده عبر خادم SMTP الخاص بذلك الحساب (مع SPF/DKIM لمزود الخدمة). يؤدي تقديم identity_id مرتبط بالمصدر بدلا منه إلى استخدام نطاق هوية الإرسال باسم أو مسار ملفها الشخصي المحفوظ، مع الاستمرار في حفظ نسخة الرسالة المرسلة في صندوق الوارد المتصل. يجب أن يكون الحساب سليما (status: active)؛ ويعيد الحساب غير المتصل خطأ يطلب منك إعادة ربطه. راجع عناوين الإرسال باسم عبر API وMCP.

أدوات MCP

تتوفر الإمكانية نفسها لوكلاء الذكاء الاصطناعي عبر MCP (على كل من خادم stdio الخاص وخادم MCP العام):

تقبل أدوات الرسائل list_messages وread_message وsend_message وlist_folders وupdate_message_flags وmove_message وdelete_message وprepare_reply وprepare_reply_all وprepare_forward الوسيطة الاختيارية external_account_id. يقبل الإرسال وإنشاء المسودات والجدولة أيضا قيمة identity_id المرتبطة بالمصدر التي يعيدها list_identities.

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