بناء أداة لإرسال البريد الإلكتروني عبر API

1. كيف يتم إرسال البريد الإلكتروني برمجيًا؟

في الوحدات السابقة، تعلمنا كيفية التفاعل مع واجهات برمجة التطبيقات (APIs) باستخدام بروتوكول HTTP ومكتبة requests. إرسال البريد الإلكتروني يتبع نفس المبدأ: برنامجنا (العميل) يتحدث إلى خادم (Server) لتنفيذ مهمة معينة.

ولكن بدلاً من استخدام HTTP بشكل مباشر، يعتمد عالم البريد الإلكتروني على بروتوكول متخصص يسمى SMTP (Simple Mail Transfer Protocol). يمكنك التفكير في SMTP على أنه "واجهة برمجة التطبيقات" أو "لغة التخاطب" القياسية لإرسال البريد عبر الإنترنت.

لإرسال بريد إلكتروني باستخدام SMTP، يحتاج برنامجنا إلى معرفة أربعة أشياء أساسية:

1. عنوان خادم SMTP: عنوان "مكتب البريد" الذي سنتعامل معه (مثلاً: smtp.gmail.com لخدمة Gmail).
2. المنفذ (Port): رقم "النافذة" المخصصة لإرسال البريد في ذلك المكتب (المنفذ 587 هو الأكثر شيوعًا للاتصالات المؤمنة).
3. اسم المستخدم (Username): عنوان بريدك الإلكتروني.
4. كلمة المرور (Password): لإثبات هويتك والسماح لك بإرسال البريد.

2. نقطة هامة جدًا: المصادقة و "كلمات مرور التطبيقات"

معظم خدمات البريد الإلكتروني الحديثة مثل Gmail لا تسمح باستخدام كلمة المرور الأساسية لحسابك مباشرةً في تطبيقات خارجية لأسباب أمنية. هذا يمنع سرقة حسابك إذا تم اختراق التطبيق.

الحل هو إنشاء "كلمة مرور للتطبيق" (App Password). وهي كلمة مرور فريدة مكونة من 16 حرفًا تمنحها Google لتطبيق معين (في حالتنا، هو سكربت بايثون الخاص بنا) للوصول إلى حسابك.

قبل أن نكتب الكود، يجب عليك إنشاء كلمة مرور للتطبيق لحساب Google الخاص بك. إليك الخطوات:

1. تأكد من تفعيل التحقق بخطوتين (2-Step Verification) على حساب Google الخاص بك. هذا شرط أساسي لإنشاء كلمات مرور التطبيقات.
2. اذهب إلى صفحة إدارة حساب Google الخاص بك (myaccount.google.com).
3. في قائمة التنقل اليسرى، اختر "الأمان" (Security).
4. ابحث عن قسم يسمى "كيفية تسجيل الدخول إلى Google" (How you sign in to Google).
5. انقر على "كلمات مرور التطبيقات" (App passwords). قد يُطلب منك تسجيل الدخول مرة أخرى.
6. في صفحة "كلمات مرور التطبيقات"، انقر على القائمة المنسدلة "تحديد تطبيق" (Select app) واختر "أخرى (اسم مخصص)" (Other (Custom name)).
7. اكتب اسمًا وصفيًا مثل "وكيل البريد بايثون" ثم انقر على "إنشاء" (GENERATE).
8. ستظهر لك كلمة المرور المكونة من 16 حرفًا في نافذة منبثقة. انسخ هذه الكلمة واحتفظ بها في مكان آمن. لن تتمكن من رؤيتها مرة أخرى بعد إغلاق النافذة.

هذه الكلمة المكونة من 16 حرفًا هي التي سنستخدمها في الكود الخاص بنا، وليس كلمة مرور حسابك العادية.

3. بناء أداة إرسال البريد الإلكتروني في بايثون

لحسن الحظ، تأتي بايثون مع مكتبات مدمجة تجعل التعامل مع SMTP أمرًا سهلاً:

• smtplib: للتواصل مع خادم SMTP.
• email.message: لبناء هيكل رسالة البريد الإلكتروني (المُرسِل، المُستقبِل، الموضوع، والمحتوى).

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

كما رأيت في الفيديو، العملية منظمة ومباشرة. الآن دعنا نجمع هذا المنطق في دالة بايثون نظيفة، والتي ستكون "الأداة" الرسمية في وكيلنا.

إليك الكود الكامل للدالة send_email مع شروحات باللغة العربية لكل سطر. قم بإنشاء ملف جديد باسم tools.py والصق الكود التالي فيه:

# tools.py

import smtplib
from email.message import EmailMessage
import os # سنستخدم هذه المكتبة لاحقًا لجعل الكود أكثر أمانًا

# تعريف عناوين البريد وكلمة المرور
# !! تنبيه: لا تضع معلوماتك الحساسة مباشرة في الكود في المشاريع الحقيقية !!
# سنقوم بتحسين هذا الجزء لاحقًا
SENDER_EMAIL = "your_email@gmail.com"
SENDER_PASSWORD = "your_16_digit_app_password"

def send_email(recipient_email, subject, body):
    """
    تقوم هذه الدالة بإرسال بريد إلكتروني باستخدام خادم SMTP الخاص بـ Gmail.
    
    :param recipient_email: البريد الإلكتروني للمستلم.
    :param subject: موضوع الرسالة.
    :param body: محتوى نص الرسالة.
    :return: True إذا تم الإرسال بنجاح، False إذا حدث خطأ.
    """
    
    # 1. إنشاء كائن الرسالة وتحديد تفاصيلها
    msg = EmailMessage()
    msg['Subject'] = subject
    msg['From'] = SENDER_EMAIL
    msg['To'] = recipient_email
    msg.set_content(body)
    
    try:
        # 2. الاتصال بخادم Gmail عبر منفذ آمن
        # استخدام `with` يضمن إغلاق الاتصال تلقائيًا
        with smtplib.SMTP_SSL('smtp.gmail.com', 465) as smtp_server:
            # 3. تسجيل الدخول إلى حسابك باستخدام كلمة مرور التطبيق
            smtp_server.login(SENDER_EMAIL, SENDER_PASSWORD)
            
            # 4. إرسال الرسالة
            smtp_server.send_message(msg)
            
        print(f"تم إرسال البريد بنجاح إلى {recipient_email}")
        return True
        
    except Exception as e:
        print(f"فشل إرسال البريد إلى {recipient_email}. الخطأ: {e}")
        return False

# --- قسم الاختبار ---
# يمكنك استخدام هذا الجزء لاختبار الدالة بشكل مستقل
if __name__ == "__main__":
    print("بدء اختبار إرسال البريد...")
    # استبدل بالبريد الذي تريد الإرسال إليه
    test_recipient = "some_test_email@example.com"
    test_subject = "رسالة اختبار من وكيل بايثون"
    test_body = "مرحبًا، هذه رسالة تم إرسالها تلقائيًا باستخدام دالة بايثون!"
    
    send_email(test_recipient, test_subject, test_body)

لتشغيل هذا الكود:

1. استبدل your_email@gmail.com ببريدك الإلكتروني.
2. استبدل your_16_digit_app_password بكلمة مرور التطبيق التي أنشأتها.
3. استبدل some_test_email@example.com بعنوان بريد إلكتروني يمكنك التحقق منه (يمكن أن يكون بريدك الشخصي).
4. افتح الطرفية (Terminal) في مجلد المشروع وقم بتشغيل الملف: python tools.py.
5. إذا سارت الأمور على ما يرام، يجب أن ترى رسالة نجاح في الطرفية وتستقبل البريد الإلكتروني في صندوق الوارد الخاص بك!

4. خطوة للأمام: تأمين بياناتك الحساسة

الكود الذي كتبناه يعمل، لكنه يحتوي على مشكلة أمنية كبيرة: كتابة كلمة المرور مباشرة في الكود (Hard-coding). هذا أمر خطير جدًا، خاصة إذا كنت ستشارك الكود أو ترفعه على منصات مثل GitHub.

الحل الأفضل هو استخدام متغيرات البيئة (Environment Variables)، وهو مفهوم تعلمناه في الوحدة الثانية. لنقم بتعديل الكود ليقرأ البيانات الحساسة من بيئة التشغيل بدلاً من الملف نفسه.

الكود المعدّل في tools.py:

# tools.py

import smtplib
from email.message import EmailMessage
import os # تأكد من استيراد هذه المكتبة

# قراءة البيانات الحساسة من متغيرات البيئة
SENDER_EMAIL = os.getenv("EMAIL_USER")
SENDER_PASSWORD = os.getenv("EMAIL_PASS")

def send_email(recipient_email, subject, body):
    # ... باقي الدالة يبقى كما هو ...
    # (نفس الكود من المثال السابق)
    # ...
    
    # تأكد من أن المتغيرات ليست فارغة
    if not SENDER_EMAIL or not SENDER_PASSWORD:
        print("خطأ: لم يتم تعيين متغيرات البيئة EMAIL_USER و EMAIL_PASS.")
        return False
        
    msg = EmailMessage()
    msg['Subject'] = subject
    msg['From'] = SENDER_EMAIL
    msg['To'] = recipient_email
    msg.set_content(body)
    
    try:
        with smtplib.SMTP_SSL('smtp.gmail.com', 465) as smtp_server:
            smtp_server.login(SENDER_EMAIL, SENDER_PASSWORD)
            smtp_server.send_message(msg)
            
        print(f"تم إرسال البريد بنجاح إلى {recipient_email}")
        return True
        
    except Exception as e:
        print(f"فشل إرسال البريد إلى {recipient_email}. الخطأ: {e}")
        return False

# ... قسم الاختبار يبقى كما هو ...

لتشغيل هذا الكود الآمن:
قبل تشغيل python tools.py، يجب عليك تعيين متغيرات البيئة في الطرفية:

• في نظامي التشغيل macOS/Linux:

  export EMAIL_USER="your_email@gmail.com"
  export EMAIL_PASS="your_16_digit_app_password"
  python tools.py
  

• في نظام Windows (Command Prompt):

  set EMAIL_USER="your_email@gmail.com"
  set EMAIL_PASS="your_16_digit_app_password"
  python tools.py
  

بهذه الطريقة، يبقى الكود نظيفًا وآمنًا، بينما تبقى بياناتك السرية منفصلة عنه.

خلاصة الدرس

لقد حققنا اليوم تقدمًا كبيرًا في بناء وكيلنا:

• فهمنا أن بروتوكول SMTP هو بمثابة الـ API لإرسال البريد الإلكتروني.
• تعلمنا أهمية استخدام كلمات مرور التطبيقات لحماية حساباتنا.
• بنينا دالة بايثون (send_email) متكاملة وقابلة لإعادة الاستخدام، وهي أول أداة عملية في صندوق أدوات وكيلنا.
• قمنا بتأمين الأداة عن طريق فصل البيانات الحساسة باستخدام متغيرات البيئة.

لقد أصبح لدى وكيلنا الآن القدرة على "التصرف" في العالم الرقمي وإرسال الرسائل.

ماذا بعد؟

الآن بعد أن أصبح لدى وكيلنا "يد" لإرسال البريد، فإنه يحتاج إلى "عين" ليقرأ قائمة الأشخاص الذين يجب مراسلتهم. في الدرس القادم، سنقوم ببناء الأداة الثانية التي صممناها: "أداة لقراءة قائمة المستلمين من ملف (مثل CSV أو JSON)". سنواصل بناء مكتبة الأدوات الخاصة بوكيلنا خطوة بخطوة.