> For the complete documentation index, see [llms.txt](https://docs.augelab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.augelab.com/arabic/alblwkat-alwzyfyh/blocks-reference/input-output/communication/send-mail.md).

# Send Mail

هذه دالة (function block) تتيح لك إرسال رسائل بريد إلكتروني باستخدام Gmail SMTP. مخصصة لإرسال رسائل نصية عادية (plain-text) ومع إمكانية إرفاق ملف واحد. يجب أن يكون حساب المرسل مُمكَّناً للوصول عبر Gmail API / SMTP.

## 📥 المدخلات (Inputs)

* `Subject` - موضوع الرسالة (نص).
* `Content` - محتوى نص الرسالة (نص).
* `Sender Address` - عنوان Gmail الذي سيرسل الرسالة (نص). يجب تهيئته لاستخدام SMTP/API.
* `Mail API Password` - كلمة المرور أو مفتاح الـ API المستخدم للمصادقة على حساب المرسل (نص).
* `Receiver Address` - عنوان البريد الإلكتروني المستلم (نص).
* `Attachment File Path` - مسار ملف كامل اختياري للإرفاق (نص). اتركه فارغاً إذا لا يوجد مرفق.
* `Trigger` - إشارة منطقية (Boolean) تُفَعِّل عملية الإرسال عند وجودها.

## 📤 المخرجات (Outputs)

* `Success` - قيمة منطقية تشير إلى نجاح عملية الإرسال (True أو False).

## 🕹️ الضوابط (Controls)

* لا يوجد زر إرسال مستقل داخل البلوك؛ الإرسال يَبدأ عند وصول إشارة `Trigger` فعالة إلى البلوك. عدّل حقول الرسالة عبر المدخلات المذكورة أعلاه.

## ⚙️ كيفية التشغيل (How it runs)

* البلوك ينتظر تزويد المدخلات وفعالية إشارة `Trigger`.
* عند التفعيل، يحاول البلوك المصادقة باستخدام بيانات المرسل وإرسال الرسالة إلى المستلم.
* إذا وُضع مسار ملف صحيح في `Attachment File Path`، يرفق الملف مع الرسالة.
* يعيد البلوك `Success = True` عند الإرسال بنجاح، وإلا فـ `False`.
* عند فشل مؤقت في المصادقة أو الإرسال، يحاول البلوك إعادة الاتصال وإعادة الإرسال تلقائياً.

## ✨ الميزات (Features)

* إرسال رسائل نصية عادية عبر Gmail SMTP.
* يدعم إرفاق ملف واحد عبر مسار الملف.
* يستخدم جلسة مخزنة (cached session) لتجنب إعادة المصادقة عند كل تفعيل إن أمكن.
* إعادة اتصال وإعادة محاولة تلقائية عند مشكلات مؤقتة في الجلسة.

## 📝 تعليمات الاستخدام (Usage)

1. جهّز بيانات اعتماد المرسل وتأكد من تمكين SMTP/API في حساب Gmail.
2. املأ المدخلات: `Subject`، `Content`، `Sender Address`، `Mail API Password`، و `Receiver Address`.
3. اختياري: ضع مسار الملف في `Attachment File Path` إذا أردت إرفاق ملف.
4. فعّل المدخل `Trigger` لإرسال الرسالة.
5. راقب مخرج `Success` لتتأكد من نجاح الإرسال.

## 💡 نصائح وحيل (Tips and Tricks)

* لالتقاط صورة من كاميرا وإرفاقها، اجمع البلوك مع `Camera USB` أو `Camera IP (ONVIF)` واحفظ الإطار باستخدام `Image Write` أو `Image Logger`، ثم ضع المسار في `Attachment File Path`.
* لإرسال إشعار لمرة واحدة عند حدث، استخدم `Rising Edge` أو `Logic Input` لإنشاء نبضة `Trigger` مرة واحدة.
* كوّن نص الرسالة ديناميكياً باستخدام `String Merge` أو حضّر سجلات منظمة باستخدام `Data to JSON` قبل الإرسال.
* لإرسال صور متعددة، استخدم `Multi Image Write` لتخزين الصور ثم أرفقها من المسارات واحداً تلو الآخر حسب الدعم.

## 🛠️ استكشاف الأخطاء وإصلاحها (Troubleshooting)

* فشل المصادقة: تحقق من أن `Sender Address` مفعل للوصول عبر SMTP/API وأن قيمة `Mail API Password` صحيحة. راجع إعدادات أمان حساب Gmail.
* المرفق لم يُرسَل: تأكد أن المسار في `Attachment File Path` يشير إلى ملف موجود ويمكن الوصول إليه من بيئة التشغيل.
* البريد لم يصل: تحقق من صحة عنوان المستلم وتحقق من صندوق الرسائل المزعجة (Spam). قيود الشبكة أو جدران الحماية قد تمنع منافذ SMTP.
* تجاهل `Trigger`: تأكد أن مدخل `Trigger` يتلقى قيمة True صريحة أو نبضة صاعدة (rising edge) أثناء التشغيل.
* انتهاء صلاحية الجلسة: البلوك يحاول إعادة الاتصال تلقائياً، لكن إذا استمرت المشكلة فقم بمراجعة الاعتمادات واتصال الشبكة.

## 🔒 الخصوصية والأمان (Privacy & Security)

* لا تخزن كلمات المرور الحساسة في مشاريع مشتركة. استخدم إدارة أسرار آمنة إن أمكن.
* قلل من صلاحيات حساب المرسل وفَعِّل إجراءات الأمان المناسبة على حساب Gmail المستخدم.