إدارة جهات الاتصال عبر API وMCP في TrekMail

يمكن التحكم في دفتر عناوين صندوق بريدك بالكامل برمجيا. تستطيع API الرسائل وأدوات MCP إنشاء جهات الاتصال وتعديلها وحذفها، والاستيراد والتصدير المجمع بصيغة CSV أو vCard، والبحث في دفتر عناوين كبير، وتنظيم الأشخاص في مجموعات. هذه هي البيانات نفسها التي تراها في بريد الويب وعملاء CardDAV، لذلك تظهر على هاتفك جهة اتصال أضافها وكيل ذكاء اصطناعي، وتكون الجهة التي أضفتها على هاتفك مرئية عبر API.

قبل أن تبدأ

• تستخدم جهات الاتصال واجهة رمز الرسائل (/api/v1/messages/...) ونطاقاتها، وليس رمز API للوحة التحكم.
• يقتصر كل استدعاء على صندوق البريد الخاص بالرمز. لا يستطيع الرمز رؤية سوى جهات الاتصال والمجموعات الخاصة به وإدارتها، ولا يمكنه الوصول إلى صندوق بريد آخر.
• تُعرّف جهات الاتصال بعنوان البريد الإلكتروني داخل صندوق البريد. يحدّث الاستيراد جهة اتصال مطابقة. وعند إنشاء جهة بعنوان موجود، تعاد الجهة الحالية بلا تغيير بدلا من إنشاء نسخة مكررة.
• تعيد استجابات القوائم حقولا واضحة وسهلة القراءة، وهي الاسم والبريد الإلكتروني والشركة والمسمى الوظيفي والهاتف والعنوان وتاريخ الميلاد والملاحظات. لا تعاد بطاقة CardDAV الخام خلف جهة اتصال متزامنة، بل تحصل دائما على النسخة المرتبة.
• يقبل الاستيراد ملفات CSV وvCard (.vcf) حتى 10 MB، ويفهم صيغ التصدير من Google Contacts وOutlook وApple وRoundcube، بما في ذلك اختلافات UTF-8 وUTF-16 وBOM.

النطاقات

إدارة جهات الاتصال

المسار الأساسي: /api/v1/messages/contacts

العرض والبحث

GET /api/v1/messages/contacts?q=alice&per_page=50&page=1
Scope: messages:read

يطابق q الاسم أو البريد الإلكتروني. تعاد النتائج في صفحات (per_page من 1-100، والافتراضي 50) مع كتلة pagination (total وper_page وcurrent_page وlast_page) حتى تتمكن من متابعة دفتر عناوين كبير حتى نهايته بدلا من التوقف عند الصفحة الأولى.

إنشاء جهة اتصال

POST /api/v1/messages/contacts
Scope: messages:write
{
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "company": "Analytical Engines",
  "job_title": "Mathematician",
  "phone": "+1 555 0100",
  "address": "London",
  "birthday": "1815-12-10",
  "notes": "Met at the conference"
}

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

الاستيراد المجمع

POST /api/v1/messages/contacts/import
Scope: messages:write
{
  "content_base64": "<base64 of your .csv or .vcf file>",
  "format": "csv"
}

أرسل الملف مشفرا بـ base64 مع ضبط format على csv أو vcf (بحد أقصى 10 MB بعد فك الترميز). تخبرك الاستجابة بعدد الصفوف المطبقة وعدد الصفوف التي تم تخطيها لعدم وجود بريد إلكتروني صالح:

{ "imported": 128, "skipped": 3 }

تُتعرف تلقائيا عناوين الأعمدة من صادرات Google وOutlook وApple وRoundcube، لذا يمكن استيراد معظم الملفات دون تعديل.

التصدير

GET /api/v1/messages/contacts/export?format=vcard
Scope: messages:read

يعيد دفتر العناوين بأكمله كملف واحد مشفر بـ base64:

{ "format": "vcard", "content_base64": "..." }

استخدم format=csv لملف مناسب لجداول البيانات أو format=vcard لملف .vcf يمكنك تحميله في عميل بريد آخر.

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

المجموعات هي قوائم توزيع داخل دفتر العناوين. المسار الأساسي: /api/v1/messages/contact-groups

عرض أعضاء المجموعة

GET /api/v1/messages/contact-groups/42/members?per_page=50&page=1
Scope: messages:read

يعيد جهات اتصال المجموعة (بالحقول المرتبة نفسها في قائمة جهات الاتصال)، إضافة إلى كتلة pagination وإجمالي contact_count للمجموعة، حتى تتمكن من قراءة عضوية المجموعة بدلا من تغييرها بلا معرفة.

إضافة الأعضاء أو إزالتهم

POST /api/v1/messages/contact-groups/42/members
Scope: messages:write
{ "contact_ids": [11, 12, 13] }

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

أدوات MCP

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

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