تكامل البريد

تكامل البريد

مهارة email-manager الأصلية تمنح الوكيل أدوات صندوق بريد كاملة: سرد، جلب، إرسال، حذف، تصنيف، وتحليل. لا يوجد أمر slash إلزامي /email — استخدم الدردشة.

بداية سريعة (sandbox — بلا إعداد)

أعد تشغيل الخادم واسأل:

• اعرض الوارد
• حلّل رسالة اليانصيب / التصيّد
• صغ ردًا إلى boss@corp.com (موافقة HITL للإرسال/المسودات)

بدون بيانات اعتماد، كل رد يُسبق بـ [sandbox mode]. البيانات في kazma-data/sandbox_emails.db.

الأدوات

الأداة	الغرض	HITL
email_list	سرد/بحث المجلد	لا
email_get	نص الرسالة كاملًا	لا
email_send	إرسال / رد / تحويل / مسودة	نعم
email_delete	سلة أو حذف دائم	نعم
email_categorize	قراءة/نجمة/تسميات/نقل	نعم
email_analyze	ملخص، إجراءات، تصيّد	لا

وسائط شائعة: provider (auto|sandbox|gmail|microsoft|imap|pop)، وaccount اختياري (اسم مستعار متعدد الحسابات).

حل المزوّد (auto)

1. provider / account صريح على استدعاء الأداة
2. EMAIL_DEFAULT_PROVIDER
3. أول حساب حقيقي مُعدّ (Gmail → Microsoft → IMAP/POP عام → أسماء متعددة)
4. Sandbox

ربط البريد (واجهة الإعدادات)

افتح الإعدادات → البريد (/settings?tab=email).

لكل من Gmail وMicrosoft مبدّل وضع: OAuth | IMAP | POP.

البطاقة	الأوضاع
Sandbox	دائمًا — بلا إعداد
Gmail / Workspace	OAuth (مُوصى، Gmail API) · IMAP · POP
Microsoft 365	OAuth (مُوصى، Graph) · IMAP · POP

الحالة تعرض المزوّد النشط (تلقائي) وشارة المصادقة (OAUTH / IMAP / POP).

البروتوكول	المضيفات (جاهزة)	ملاحظات
Gmail IMAP	imap.gmail.com:993، smtp.gmail.com:587	كلمة مرور تطبيق؛ فعّل IMAP
Gmail POP	pop.gmail.com:995، smtp.gmail.com:587	وارد فقط؛ بلا مسودات/تسميات
MS IMAP	outlook.office365.com:993، smtp.office365.com:587	المصادقة الأساسية غالبًا معطّلة → OAuth
MS POP	outlook.office365.com:995، smtp.office365.com:587	نفس قيد المصادقة

API:

POST /api/email/protocol/connect
{"provider":"gmail"|"microsoft"|"generic","protocol":"imap"|"pop","address":"...","password":"..."}

POST /api/email/protocol/disconnect
{"provider":"gmail"|"microsoft"|"generic"}

GET /api/email/presets

إعداد Gmail OAuth (مناسب لـ Workspace)

1. Google Cloud Console → APIs & Services → فعّل Gmail API.
2. شاشة موافقة OAuth → أضف النطاقات gmail.modify، gmail.send، userinfo.email.
3. بيانات الاعتماد → OAuth client ID → نوع Web application.
4. URI إعادة التوجيه المصرّح:

http://127.0.0.1:9090/api/email/oauth/gmail/callback
https://your.domain/api/email/oauth/gmail/callback

5. الإعدادات → البريد → الصق Client ID + السر → حفظ عميل OAuth → الاتصال بـ Google.

بديل Env:

EMAIL_GMAIL_CLIENT_ID=...
EMAIL_GMAIL_CLIENT_SECRET=...
# بعد OAuth تُخزَّن الرموز تلقائيًا:
# EMAIL_GMAIL_ACCESS_TOKEN / EMAIL_GMAIL_REFRESH_TOKEN (وأيضًا vault)

كلمات مرور التطبيقات ما زالت تعمل لـ Gmail الشخصي إن سمح المشرف؛ OAuth مُفضَّل لـ Workspace.

خطأ: «Kazma has not completed the Google verification process» / 403: access_denied

تطبيق OAuth في وضع Testing. Google يسمح فقط بمستخدمي الاختبار حتى يُتحقَّق من التطبيق.

الإصلاح للاستخدام الشخصي / مستخدم واحد:

1. Google Cloud → OAuth consent screen.
2. حالة النشر Testing.
3. Test users → أضف Gmail الذي تسجّل به.
4. احفظ، انتظر ~دقيقة، أعد الاتصال بـ Google.
5. قد ترى «Google hasn’t verified this app» → Continue — متوقَّع للمشاريع الشخصية.

لا تحتاج تحقق Google كاملًا إلا إن نشرت كاظمة كمنتج متعدد المستأجرين لمستخدمين عشوائيين.

خطأ: insufficientPermissions / نطاقات غير كافية

نجح OAuth لكن الرمز بلا نطاقات Gmail. Gmail API يعيد 403.

الإصلاح (مطلوب — أعد الاتصال):

1. فعّل Gmail API.
2. أضف النطاقات:
   • https://www.googleapis.com/auth/gmail.modify
   • https://www.googleapis.com/auth/gmail.send
3. افصل Gmail في كاظمة ثم اتصل بـ Google مجددًا.
4. على شاشة Google يجب أن ترى صلاحيات Gmail وليس «عرض عنوان بريدك» فقط.
5. جرّب: اعرض الوارد.

إعداد Microsoft Graph OAuth

1. تسجيل تطبيق Azure → Web redirect URI:

http://127.0.0.1:9090/api/email/oauth/microsoft/callback

2. صلاحيات مفوّضة: Mail.Read، Mail.ReadWrite، Mail.Send، offline_access.
3. الإعدادات → البريد → Client ID (+ سر إن لزم) → الاتصال بـ Microsoft.

كود الجهاز يبقى تحت «بديل: device code».

EMAIL_MS_CLIENT_ID=...
EMAIL_MS_CLIENT_SECRET=...
EMAIL_MS_TENANT_ID=common
EMAIL_MS_REDIRECT_URI=http://127.0.0.1:9090/api/email/oauth/microsoft/callback

عيّن KAZMA_PUBLIC_URL=https://your.domain خلف reverse proxy.

أسماء مستعارة متعددة الحسابات

EMAIL_ACCOUNTS=personal,work

EMAIL_ACCOUNT_PERSONAL_TYPE=gmail
EMAIL_ACCOUNT_PERSONAL_ADDRESS=me@gmail.com
EMAIL_ACCOUNT_PERSONAL_PASSWORD=app-password

EMAIL_ACCOUNT_WORK_TYPE=microsoft
EMAIL_ACCOUNT_WORK_REFRESH_TOKEN=...
EMAIL_ACCOUNT_WORK_CLIENT_ID=...

في الدردشة: اعرض وارد work → account=work.

GET /api/email/status
GET /api/email/accounts

التحليل

email_analyze يستخدم LLM النشط إن وُجد؛ وإلا كاشف تصيّد/إجراءات استكشافي. راجع دائمًا security.risk_level على رسائل البنوك/اليانصيب.

الأمان

• أدوات التعديل تتطلب موافقة HITL.
• لا تلصق كلمات مرور التطبيقات في الدردشة؛ استخدم env أو vault.
• Sandbox لا يرسل بريدًا حقيقيًا أبدًا.
• Graph OAuth هو مسار M365 المُوصى؛ IMAP/POP يعملان فقط إن سمح المستأجر.
• POP موجَّه للوارد؛ فضّل IMAP أو OAuth.

ذات صلة

• الخطة: docs/plans/EMAIL_INTEGRATION_FULL_PLAN.md
• متغيرات البيئة
• كتالوج الأدوات