دمج البريد الإلكتروني

دمج البريد الإلكتروني

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

البدء السريع (البيئة الرملية — صفر إعدادات)

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

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

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

الأدوات

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

تعطي القائمة لكل رسالة مرسلها وتاريخها وموضوعها (الموضوعات حتى 150 حرفًا، والمرسلون حتى 80)، فيستطيع الوكيل أن يجيب عن “ما الذي وصل اليوم” دون فتح كل رسالة.

الوسائط الشائعة: provider (auto|sandbox|gmail|microsoft|imap|pop)، وaccount اختياري (أي صندوق بريد: اسم الحساب أو عنوانه؛ انظر أكثر من حساب).

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

1. provider / account صريحان في استدعاء الأداة
2. EMAIL_DEFAULT_PROVIDER
3. أول حساب حقيقي مضبوط (Gmail → Microsoft → IMAP/POP عام → بقية الحسابات)
4. البيئة الرملية (sandbox)

المزوّد أو الحساب المسمّى في الخطوتين 1–2 الذي غير متصل يُرفَض (“Gmail is not connected. Settings → Email → …”)، ولا تُجاب أبدًا من البيئة الرملية — القاعدة نفسها يتبعها التقويم. اسم مزوّد غير معروف أو اسم مستعار لحساب مكتوب خطأً يُرفض كذلك. تجيب البيئة الرملية فقط auto مع لا شيء متصل، أو provider=sandbox، أو حساب TYPE لديه sandbox.

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

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

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

البطاقة	الأوضاع
البيئة الرملية	مفعَّلة دائمًا — بلا إعداد
Gmail / Workspace	OAuth (موصى به، Gmail API) · IMAP (imap.gmail.com + كلمة مرور تطبيق) · POP (pop.gmail.com + كلمة مرور تطبيق)
Microsoft 365	OAuth (موصى به، Graph) · IMAP (outlook.office365.com) · POP (outlook.office365.com:995)

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

البروتوكول	المضيفون (جاهزون)	ملاحظات
Gmail IMAP	imap.gmail.com:993، smtp.gmail.com:587	كلمة مرور تطبيق؛ فعِّل IMAP في Gmail
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 وGoogle Calendar API.
2. شاشة موافقة OAuth → أضف النطاقات gmail.modify، وgmail.send، وcalendar، وuserinfo.email.
3. Credentials → 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 + السر → Save OAuth client → Connect with Google. تلك الموافقة تطلب التقويم أيضًا. إذا تم تخطّي التقويم أو كانت Calendar API مطفأة، فاستخدم Connect Google Calendar على بطاقة التقويم في الصفحة نفسها (العميل نفسه، وعنوان URI لإعادة التوجيه نفسه).

بطاقة التقويم فيها صف لكل تقويم، لكل صف حالته الخاصة، وزر Connect الخاص به، وزر Disconnect الخاص به:

• Connect Outlook Calendar يسجّل الدخول إلى Microsoft للتقويم وحده؛ ويُترك بريد Microsoft كما هو. يستخدم معرّف تطبيق Azure (العميل) المحفوظ على بطاقة Microsoft وعنوان URI لإعادة التوجيه نفسه. عندما ترفض Microsoft إعادة التوجيه (تطبيق مسجَّل لرمز الجهاز فقط)، فإن زر Connect with a code instead على البطاقة يفعل الشيء نفسه عبر رمز.
• Disconnect يعطّل ذلك التقويم حتى تعيد توصيله من البطاقة. تسجيل دخول البريد يغطي التقويم أيضًا، ولذلك كان حذف رموز التقويم وحدها سيتركه يقرأ عبر منحة البريد؛ وأثناء تعطّل تقويم ما، لا شيء يقرأ رموزه أو يحتفظ بها. البريد يبقى متصلًا.
• قطع اتصال بريد Gmail أو Microsoft يترك التقويم في صفه الخاص متصلًا؛ اقطع اتصاله هناك.

لا يمكن لرموز Gmail-فقط سرد أحداث Google Calendar. كانت مهارة التقويم تعود بصمت إلى بيئة رملية فارغة؛ وهي الآن تفشل مغلقةً مع تلميح اتصال عندما لا يملك provider=google منحة تقويم.

بديل متغيرات البيئة:

EMAIL_GMAIL_CLIENT_ID=...
EMAIL_GMAIL_CLIENT_SECRET=...
# After OAuth, tokens are stored automatically:
# EMAIL_GMAIL_ACCESS_TOKEN / EMAIL_GMAIL_REFRESH_TOKEN (also vault)

ما تزال كلمات مرور التطبيق تعمل لحساب Gmail الشخصي إذا سمح مشرفك بها؛ وOAuth موصى به لـWorkspace.

خطأ: «لم تكمل كاظمه عملية التحقق من Google» / 403: access_denied

تطبيق OAuth لديك في وضع Testing. لا تسمح Google إلا بالمستخدمين التجريبيين حتى يُتحقق من التطبيق (نطاقات Gmail «حساسة/مقيَّدة»).

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

1. Google Cloud Console → APIs & Services → OAuth consent screen.
2. افتح Test users → Add users → أضف حساب Gmail الذي تسجّل الدخول به (مثل you@gmail.com).
3. احفظ، وانتظر ~1 دقيقة، وجرّب Connect with Google مجددًا.
4. على شاشة الموافقة سترى «Google hasn’t verified this app» → Advanced → الانتقال إلى كاظمه (غير آمن) — أمر متوقع لمشروع شخصي غير متحقق منه.

لا تحتاج إلى تحقق Google الكامل إلا إذا أطلقت كاظمه كمنتج متعدد المستأجرين لمستخدمي Gmail عشوائيين.

خطأ: 401: invalid_client / «لم يتم العثور على عميل OAuth»

لا تستطيع Google العثور على عميل بالمعرف الذي أرسلته. هذه مشكلة بيانات اعتماد، وليست مشكلة نشر أو نطاقات — شاشة الموافقة لا تُحمَّل أبدًا.

في كل مرة تقريبًا يكون حقل Client ID يحمل Client Secret. الحقلان يجلسان جنبًا إلى جنب في Cloud Console ويتشابهان:

الحقل	يبدو دائمًا مثل
معرِّف (ID) العميل	1234567890-abcdef.apps.googleusercontent.com
سر (Secret) العميل	GOCSPX-…

الإصلاح: Google Cloud Console → APIs & Services → Credentials → معرف OAuth 2.0 Client ID لديك → انسخ Client ID (الطويل المنتهي بـ .apps.googleusercontent.com) → الإعدادات → البريد الإلكتروني → OAuth → أعد حفظ الحقلين → Connect with Google.

ترفض كاظمه الآن الزوج غير المتطابق عند حفظه، ومرة أخرى عند نقرك على الاتصال، مع تسمية الحقل. كلا الفحصين للتنسيق فقط — العميل جيد التشكيل الذي تم حذفه في Console يفشل عند Google مع ذلك.

Testing مقابل In production — اختر واحدًا بتعمد

حالة النشر ليست تجميلية؛ إنها تحدد مدى تكرار إعادة الاتصال لديك.

	Testing	In production (غير متحقق منه)
من يستطيع الاتصال	الحسابات في قائمة Test users فقط (الحد الأقصى 100)	أي شخص، حتى سقف 100 مستخدم أثناء عدم التحقق
مدة صلاحية رمز التحديث	تنتهي بعد 7 أيام — تعيد الاتصال أسبوعيًا	لا تنتهي بمؤقت
شاشة الموافقة	تحذير «Google hasn’t verified this app»	التحذير نفسه حتى التحقق
التحقق مطلوب	لا	فقط لرفع السقف / إزالة التحذير

لتثبيت ذاتي أحادي المشغِّل، يكون In production عادة الخيار الأفضل: النطاقات وشاشة التحذير متطابقة، وإعادة اتصال invalid_grant الأسبوعية تختفي. النشر لا يقدّم أي شيء للمراجعة — التحقق خطوة منفصلة يمكنك رفضها.

:::note بعد التحويل إلى In production، أعد الاتصال مرة واحدة رمز التحديث الصادر بينما كان التطبيق في وضع Testing يحمل ساعته ذات 7 أيام؛ النشر لا يمدّ رمزًا موجودًا مسبقًا. اذهب إلى الإعدادات → البريد الإلكتروني → Disconnect، ثم Connect with Google مجددًا لسكّ رمز دائم. تخطّي هذا يبدو تمامًا كأن الإصلاح لم يعمل، بعد أسبوع. :::

نطاقا Gmail gmail.modify / gmail.send نطاقان مقيَّدان، لذا فالتطبيق غير المتحقق منه — Testing أو منشور — يعرض شاشة التحذير دائمًا ومحصور بـ100 مستخدم. ذلك السقف غير ذي صلة بالاستضافة الذاتية وهو الشيء الوحيد الذي يشتريه لك التحقق.

Workspace: إذا كان الحساب مستخدم Google Workspace لشركة، فقد يحجب المشرف OAuth لطرف ثالث مع ذلك؛ استخدم مستخدمًا تجريبيًا شخصيًا أو تطبيقًا صادقًا عليه المشرف.

خطأ: Request had insufficient authentication scopes / insufficientPermissions

نجح OAuth «ظاهريًا» لكن الرمز يحمل الملف الشخصي/البريد فقط (أو لا نطاقات Gmail). تعيد Gmail API عندئذ 403.

الإصلاح (مطلوب — الرمز الحالي لن يعمل أبدًا حتى إعادة الاتصال):

1. Google Cloud → APIs & Services → فعِّل Gmail API.
2. OAuth consent screen → Data access / Scopes → Add or remove scopes → أضف:
   • https://www.googleapis.com/auth/gmail.modify
   • https://www.googleapis.com/auth/gmail.send
     (اختياري: …/auth/userinfo.email)
3. احفظ. تأكد أنك Test user.
4. كاظمه الإعدادات → البريد الإلكتروني → Disconnect لـGmail.
5. Connect with Google مجددًا.
6. على واجهة موافقة Google يجب أن ترى Gmail / Read, compose, send, and permanently delete all your email (الصياغة تختلف) — وليس «See your email address» فقط. وافق على تلك.
7. أعد المحاولة في الدردشة: اسرد صندوق الوارد لديّ.

إذا طلبت الموافقة عنوان البريد الإلكتروني فقط، فلم تُضَف النطاقات قط في مشروع Cloud — أصلح الخطوة 2، ثم اقطع الاتصال وأعد توصيله.

إعداد Microsoft Graph OAuth

1. تسجيل تطبيق Azure → عنوان URI لإعادة توجيه الويب:

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

2. أذونات مفوَّضة: Mail.Read، وMail.ReadWrite، وMail.Send، وoffline_access.
3. الإعدادات → البريد الإلكتروني → Client ID (+ السر إذا كان عميلًا سريًا) → Connect with Microsoft.

يظل رمز الجهاز متاحًا تحت «Alternative: device code».

EMAIL_MS_CLIENT_ID=...
EMAIL_MS_CLIENT_SECRET=...   # if required
EMAIL_MS_TENANT_ID=common
EMAIL_MS_REDIRECT_URI=http://127.0.0.1:9090/api/email/oauth/microsoft/callback  # optional override

اضبط KAZMA_PUBLIC_URL=https://your.domain خلف وكيل عكسي حتى تُحلّ عناوين URI لإعادة التوجيه بشكل صحيح.

أكثر من حساب

تصل بطاقتا Gmail وMicrosoft الحسابَين الرئيسيين. أي عدد من صناديق البريد الأخرى — ثلاثة حسابات Gmail، وOutlook ثانٍ، وخادم IMAP للعمل — يُضاف في الإعدادات → البريد الإلكتروني → حسابات أخرى:

• إضافة حساب Google / إضافة حساب Microsoft: تعطي الحساب اسمًا قصيرًا يُستخدم في الدردشة (work، وpersonal؛ حروف a–z، وأرقام، وشرطات)، ثم تسجّل الدخول. يطلب تسجيل الدخول اختيار الحساب المطلوب، فمتصفح مسجَّل الدخول إلى عدة حسابات Google أو Microsoft يختار الذي تختاره. تسجيل التطبيق نفسه في Google أو Microsoft يُدخل كل حساب، وعنوان URI لإعادة التوجيه الخاص به هو الذي سجّلته مسبقًا. عندما ترفض Microsoft إعادة التوجيه (تطبيق Azure مسجَّل لرمز الجهاز فقط)، فإن إضافة حساب Microsoft برمز يفعل الشيء نفسه عبر رمز.
• إضافة بكلمة مرور: كلمة مرور تطبيق لـGmail، أو خادم IMAP/POP مع مضيفه. تجرّب كاظمه تسجيل الدخول قبل الاحتفاظ بالحساب، وترفض حسابًا لا يعمل وفق رد الخادم.
• إعادة الاتصال تسجّل الحساب من جديد باسمه؛ وإزالة تنسى تسجيل دخوله (صندوق البريد نفسه لا يُمَس). العنوان المتصل مسبقًا — كحساب رئيسي أو حساب آخر — يُرفض.

في الدردشة، سمِّ الحساب أو عنوانه: “تفقّد وارد العمل لديّ”، “أرسل هذا من personal@gmail.com”، “ماذا في تقويم الفريق غدًا”. أداة email_accounts لدى الوكيل تسرد كل حساب مع اسمه وعنوانه وهل هو مسجَّل الدخول وهل تقويمه قابل للاستخدام، وكل أداة بريد وتقويم تقبل account= (اسمًا، أو عنوانًا، أو gmail / microsoft لأحد الحسابين الرئيسيين). دون حساب مسمّى، يجيب الحساب الرئيسي للمزوّد، كما كان من قبل. بطاقة الموافقة على الإرسال تعرض الحساب.

تقويم حساب Google أو Microsoft يأتي مع تسجيل دخوله عندما تمنح شاشة الموافقة وصول التقويم؛ أما حساب كلمة المرور فلا تقويم له.

يحتفظ كل حساب برموزه الخاصة (الخزنة، تحت email.account.<name>.*) وكل تحديث يكتب مفاتيح ذلك الحساب فقط. القائمة نفسها (الأسماء، والعناوين، وأيها لديه تقويم) هي الإعداد email.accounts.

ما تزال الحسابات قابلة للكتابة في .env؛ وتُعرض بشارة .env وتُغيَّر هناك، لا في الإعدادات:

EMAIL_ACCOUNTS=personal,work

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

الحالة:

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

التحليل

يستخدم email_analyze نموذج اللغة النشط عند توفره؛ وإلا فكاشف تصيّد/إجراءات استدلالي. تحقق دائمًا من security.risk_level على رسائل اليانصيب/البنك المريبة.

السلامة

• الأدوات المعدِّلة تتطلب موافقة HITL (البوابات نفسها كالملفات/الصدفة).
• لا تلصق كلمات مرور التطبيق في الدردشة أبدًا؛ استخدم البيئة أو الخزنة.
• البيئة الرملية لا ترسل بريدًا حقيقيًا أبدًا.
• Graph OAuth هو مسار M365 الموصى به؛ المصادقة الأساسية لـIMAP/POP تعمل فقط حين يسمح بها المستأجر مع ذلك.
• POP موجَّه نحو الوارد (لا مجلدات/تصنيفات/مسودات)؛ فضِّل IMAP أو OAuth عندما يمكن.

ذو صلة

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