12 يومًا من DigitalOcean (اليوم 12) – إرسال رسائل تأكيد عبر Resend

الدروس التعليمية
Flask Python

مرحبًا بكم في اليوم الأخير من سلسلة 12 يومًا من DigitalOcean! لقد قطعنا شوطًا طويلًا، حيث قمنا ببناء خدمة معالجة الإيصالات عبر البريد الإلكتروني التي تستخرج تفاصيل الإيصالات من Postmark باستخدام وكيل GenAI من DigitalOcean، وتخزن المرفقات بشكل آمن في DigitalOcean Spaces، وتحفظ البيانات المستخرجة في Google Sheets.

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

🚀 ما ستتعلمه

بنهاية هذا الدليل، ستعرف كيفية:

  1. استخدام واجهة برمجة التطبيقات Resend لإرسال رسائل التأكيد بشكل برمجي.
  2. قم بإدارة بيانات الاعتماد الحساسة بشكل آمن باستخدام متغيرات البيئة.
  3. قم بتنسيق وإرسال رسائل البريد الإلكتروني المعاملاتية مع تفاصيل الإيصالات وروابط المرفقات وعناوين جداول البيانات.
  4. اختبر واستكشاف الأخطاء في سير عمل معالجة البريد الإلكتروني الكامل.

🛠 ما ستحتاجه

إذا كنت ترغب في البناء بالتوازي، نفترض أنك اتبعت اليوم 11: حفظ بيانات الإيصال والمرفقات في جوجل شيتس ولديك بالفعل:

إذا كنت مهتمًا فقط بتعلم كيفية دمج Resend لإرسال رسائل البريد الإلكتروني للتأكيد، ستحتاج إلى:

  • حساب Resend: اشترك في Resend.
  • مفتاح API: قم بإنشائه من لوحة معلومات Resend الخاصة بك.

الخطوة 1: إنشاء حساب Resend والحصول على مفتاح API

لإرسال رسائل البريد الإلكتروني برمجيًا، سنستخدم Resend، وهي واجهة برمجة تطبيقات سهلة الاستخدام للمطورين لإرسال الرسائل الإلكترونية المعاملات. تسهل إرسال الرسائل بحيث لا تحتاج إلى التعامل مع إعداد خادم البريد الإلكتروني، أو إدارة تكوينات SMTP، أو القلق بشأن مرشحات البريد العشوائي.

  1. أولاً، انتقل إلى Resend وقم بالتسجيل للحصول على حساب مجاني. بمجرد تسجيل الدخول، انتقل إلى قسم مفاتيح API في لوحة التحكم وأنشئ مفتاح API جديد.

  2. أعط مفتاح API الخاص بك اسمًا وصفيًا، مثل تطبيق معالجة الإيصالات، وحدد إذنًا له على أنه وصول كامل.

  3. انسخ مفتاح API: سيتم عرض مفتاح API الخاص بك مرة واحدة فقط – انسخه واحتفظ به في مكان آمن. ستحتاج إليه في الخطوة التالية لمصادقة تطبيقك مع Resend.

الخطوة 2: تحديث متغيرات البيئة الخاصة بك

الآن بعد أن حصلنا على مفتاح API الخاص بـ Resend، دعنا نحفظه كمتغير بيئة في DigitalOcean، تمامًا كما فعلنا طوال هذه السلسلة.

بالنسبة لدمج Resend، نحتاج إلى حفظ متغيرين بيئيين:

  • RESEND_API_KEY: مفتاح API الذي أنشأته في الخطوة 1، والذي يصادق على تطبيقك مع Resend.
  • RESEND_EMAIL_FROM: عنوان البريد الإلكتروني للمرسل الذي ستستخدمه لإرسال رسائل التأكيد. يجب أن يكون عنوانًا تم التحقق منه في حسابك على Resend.

لإضافة هذه المتغيرات، اتبع الخطوات التالية:

  1. انتقل إلى لوحة التحكم الخاصة بـ DigitalOcean App Platform، وابحث عن تطبيق Flask الخاص بك، وانتقل إلى علامة التبويب الإعدادات. تحت متغيرات البيئة، أضف المتغيرين التاليين:

    • المفتاح: RESEND_API_KEY

      • القيمة: ألصق مفتاح API الذي أنشأته في الخطوة 1.

    • المفتاح: RESEND_EMAIL_FROM

      • القيمة: أدخل عنوان بريد إلكتروني مرسل تم التحقق منه من حساب Resend الخاص بك.

  2. احفظ تغييراتك لجعل مفتاح API الخاص بـ Resend متاحًا لتطبيق Flask الخاص بك، والذي سنقوم بتحديثه بعد ذلك.

الخطوة 3: تثبيت مكتبة بايثون Resend

بعد ذلك، سنقوم بتثبيت مكتبة بايثون Resend للتعامل مع واجهة برمجة التطبيقات (API) نيابة عنا. إنها تُبقي الشيفرة الخاصة بك نظيفة وتجنب التعامل مع طلبات HTTP الخام. قم بتشغيل هذا في الطرفية الخاصة بك:

pip install resend

الخطوة 4: تحديث requirements.txt

بدلاً من تعديل requirements.txt يدويًا، استخدم pip freeze لعرض جميع التبعيات المثبتة مع الإصدارات الدقيقة. قم بتشغيل هذا:

pip freeze > requirements.txt

هذا يحدث requirements.txt مع كل ما تحتاجه تطبيقك، بما في ذلك resend.

الخطوة 5: كتابة الدالة لإرسال البريد الإلكتروني

الآن حان الوقت لإضافة المنطق لإرسال رسائل البريد الإلكتروني للتأكيد. فكر في الأمر كما لو كنت ترسل بريدًا إلكترونيًا لصديق لإعلامه بأن طردهم قد وصل—فقط هنا، الأمر يتعلق بالإيصالات.

سنكتب دالة send_confirmation_email التي تأخذ بريد المستلم، تفاصيل الإيصال، روابط المرفقات، وعنوان ورابط جدول بيانات Google. باستخدام Resend، ستقوم بتنسيق ذلك في بريد إلكتروني وإرساله. إليك الدالة:

def send_confirmation_email(to_email, receipt_data, attachment_urls, spreadsheet_url):
    """
    Send a confirmation email with receipt details and attachment URLs.
    """
    email_from = os.getenv('RESEND_EMAIL_FROM')  # ضع هذا في متغيرات البيئة الخاصة بك
    subject = "Receipt Processed Successfully"
    email_body = f"""
    <h1>Receipt Confirmation</h1>
    <p>Your receipt has been successfully processed. Here are the details:</p>
    <ul>
        <li><strong>Vendor:</strong> {receipt_data.get('vendor', 'N/A')}</li>
        <li><strong>Amount:</strong> {receipt_data.get('amount', 'N/A')}</li>
        <li><strong>Currency:</strong> {receipt_data.get('currency', 'N/A')}</li>
        <li><strong>Date:</strong> {receipt_data.get('date', 'N/A')}</li>
    </ul>
    <p><strong>Attachments:</strong></p>
    <ul>
        {''.join(f'<li><a href="{url["url"]}">{url["file_name"]}</a></li>' for url in attachment_urls)}
    </ul>
    <p>You can view the processed data in the spreadsheet: <a href="{spreadsheet_url}">Google Spreadsheet</a></p>
    """
    try:
        resend.Emails.send({
            "from": email_from,
            "to": to_email,
            "subject": subject,
            "html": email_body
        })
        logging.info(f"Confirmation email sent to {to_email}.")
    except Exception as e:
        logging.error(f"Failed to send confirmation email: {e}")

الخطوة 5: نشر على DigitalOcean

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

  1. رفع الكود المحدث إلى GitHub: بعد إجراء التغييرات اللازمة على تطبيق Flask الخاص بك، قم بعمل commit ورفع الكود المحدث إلى GitHub. سيؤدي هذا إلى تنشيط عملية النشر التلقائي في منصة التطبيقات التابعة لشركة DigitalOcean.

    git add .
git commit -m "Add Resend integration for confirmation emails"
git push origin main

  2. راقب النشر: يمكنك تتبع التقدم في قسم النشر في لوحة التحكم الخاصة بتطبيقك.

  3. تحقق من نشر تطبيقك: بعد اكتمال النشر، انتقل إلى عنوان URL العام لتطبيقك واختبر وظيفته. يمكنك أيضًا التحقق من سجلات التشغيل في لوحة التحكم للتأكد من أن التطبيق بدأ بنجاح.

  4. تحقق من سجلات التشغيل: إذا لم يعمل شيء كما هو متوقع، استخدم علامة سجلات التشغيل في لوحة تحكم منصة التطبيقات لاستكشاف مشكلات التشغيل. ابحث عن أي أخطاء تتعلق بـ Resend API أو مكونات التطبيق الأخرى.

الخطوة 5: اختبار سير العمل بالكامل

الآن بعد أن تم تكوين تطبيقك بالكامل وجاهز، حان الوقت لاختبار سير العمل بالكامل. سنتأكد من أن نص البريد الإلكتروني قد تم معالجته، والمرفقات قد تم فك تشفيرها و تحميلها إلى DigitalOcean Spaces، وتفاصيل الإيصالات وعناوين المرفقات قد تم حفظها في Google Sheets، وأن بريد تأكيد قد تم إرساله إلى المرسل.

إليك كيفية اختبار الخطوات خطوة بخطوة:

  1. أرسل بريد اختبار: أرسل بريدًا إلكترونيًا إلى Postmark مع نص ومرفق. إذا لم تكن متأكدًا من كيفية تكوين Postmark، تحقق من اليوم 8: ربط Postmark بتطبيق Flask الخاص بك، حيث استعرضنا إعداد Postmark لإعادة توجيه البريد الإلكتروني إلى تطبيقك.

  2. تحقق من JSON نشاط Postmark: في لوحة التحكم الخاصة بـ Postmark، انتقل إلى علامة التبويب النشاط. ابحث عن البريد الإلكتروني الذي أرسلته وتأكد من أن الحمولة JSON تتضمن النص المضمن وبيانات المرفق المشفرة بـ Base64. هذا يؤكد أن Postmark يقوم بإعادة توجيه بيانات البريد الإلكتروني إلى تطبيقك بشكل صحيح، كما قمنا بإعداده في اليوم الثامن.

  3. راقب السجلات: تحقق من سجلات التشغيل في لوحة تحكم DigitalOcean App Platform الخاصة بك للتأكد من أن التطبيق يعالج حمولة JSON. يجب أن تظهر السجلات التي توضح استخراج تفاصيل الإيصال وتحميل المرفقات إلى DigitalOcean Spaces. يمكنك الوصول إلى سجلات التشغيل في علامة السجلات في لوحة تحكم DigitalOcean App Platform. إذا كنت غير معتاد على سجلات DigitalOcean، قمنا باستكشاف هذا خلال اليوم 9: التحليل التلقائي للإيصالات مع عامل GenAI من DigitalOcean.

  4. تحقق من رفع الملفات إلى المساحة: قم بزيارة مساحتك على DigitalOcean للتحقق مما إذا تم رفع الملفات بنجاح. يجب رؤية المرفقات في دلوك كما تم تكوينه في اليوم 10: تخزين المرفقات في مساحات DigitalOcean. إذا كان كل شيء حدث كما هو متوقع، ستكون عناوين URL للمرفقات الخاصة بك قابلة للوصول.

  5. تحقق من جداول Google Sheets: افتح ورقة البيانات الخاصة بك على Google وتحقق من أن تمت إضافة صف جديد بتفاصيل الإيصال وعناوين URL الخاصة بالمرفقات، كما قمنا بتهيئته في اليوم 11: حفظ تفاصيل الإيصال في جداول Google. يجب أن يتضمن الصف:

    • اسم البائع، المبلغ، العملة، والتاريخ المستخرجة من جسم البريد الإلكتروني.
    • عناوين URL مفصولة بفواصل للمرفقات المرفوعة في العمود الأخير.

  6. تحقق من بريد التأكيد الإلكتروني: أخيرًا، تحقق من صندوق الوارد لعنوان البريد الإلكتروني للمرسل للتأكد من استلام بريد التأكيد. يجب أن يحتوي هذا البريد الإلكتروني على:

    • تفاصيل الإيصال المستخرجة (البائع، المبلغ، العملة، والتاريخ).
    • روابط للمرفقات التي تم تحميلها في DigitalOcean Spaces.
    • رابط إلى جدول بيانات Google حيث يتم تسجيل بيانات الإيصال.

استكشاف الأخطاء وإصلاحها

إذا لم يعمل سير العمل كما هو متوقع، إليك بعض خطوات استكشاف الأخطاء وإصلاحها التي يجب اتباعها:

  1. تحقق من لوحة معلومات إعادة إرسال البريد الإلكتروني للأخطاء: قم بزيارة لوحة معلومات إعادة الإرسال للتحقق مما إذا كانت هناك أي أخطاء حدثت أثناء إرسال بريد التأكيد.

  2. تحقق من متغيرات البيئة: تأكد من أن مفتاح واجهة برمجة التطبيقات (RESEND_API_KEY) والبريد الإلكتروني للمرسل (RESEND_EMAIL_FROM) تم تكوينهما بشكل صحيح في متغيرات البيئة على لوحة معلومات منصة تطبيق DigitalOcean.

  3. افحص سجلات وقت التشغيل في DigitalOcean: افتح علامة التبويب سجلات وقت التشغيل في لوحة معلومات منصة تطبيق DigitalOcean للتحقق من الأخطاء أثناء معالجة البريد الإلكتروني أو تحميل المرفقات. يمكن أن توفر هذه السجلات رؤى مفيدة، خاصة للتفاعلات مع Postmark أو Resend.

  4. راجع نشاط Postmark: في علامة التبويب النشاط الخاصة بـ Postmark، تأكد من أن البريد الإلكتروني التجريبي تم تحويله بشكل صحيح إلى تطبيق Flask الخاص بك. إذا كانت هناك أي مشاكل، سيعرض Postmark أخطاء تتعلق بالتحويل أو مشكلات التكوين.

🎁 النهاية

تهانينا! لقد أكملت بنجاح سلسلة 12 يومًا من DigitalOcean وبنيت خدمة معالجة الإيصالات عبر البريد الإلكتروني وظيفية بالكامل.

اليوم، أنت:

  • دمجت واجهة برمجة التطبيقات Resend لإرسال رسائل البريد الإلكتروني المعاملات.
  • قمت بتكوين المتغيرات البيئية لإدارة بيانات الاعتماد الحساسة بأمان.
  • أرسلت رسائل تأكيد بالبريد الإلكتروني تحتوي على تفاصيل الإيصال وروابط المرفقات ورابط جدول البيانات.
  • اختبرت سير العمل الكامل من تقديم البريد الإلكتروني إلى التأكيد النهائي.

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

📚 The 12 Days of DigitalOcean

هذا يعتبر نهاية سلسلة 12 Days of DigitalOcean. خلال الـ12 يومًا الماضية، قمنا ببناء تطبيقين حقيقيين خطوة بخطوة. على طول الطريق، استخدمت أدوات مثل Serverless Functions من DigitalOcean، App Platform، Spaces Object Storage، PostgreSQL، DigitalOcean GenAI، Twilio، Google Sheets API، Postmark، PaperTrail، و Resend. اجتمعت كل قطعة لتشكل شيئًا أكبر من مجموع أجزائها.

إليك ملخص سريع لما قمت ببنائه:

🎂 Days 1–6: قم ببناء خدمة تذكير بأعياد الميلاد

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

بحلول اليوم السادس، لديك خدمة مؤتمتة بالكامل تعمل في السحابة. إنها تعمل فقط.

📧 الأيام 7–12: بناء معالج إيصالات البريد الإلكتروني

هذا التطبيق يتعامل مع الإيصالات المرسلة عبر البريد الإلكتروني، ويستخرج التفاصيل اللازمة، وينظم كل شيء في قاعدة بيانات.

بحلول اليوم 12، لقد أنشأت أداة كاملة تتعامل مع الإيصالات من البداية إلى النهاية.

ما تعلمته

  1. تخزين وإدارة البيانات: لقد استخدمت PostgreSQL لتخزين البيانات الهيكلية و Google Sheets لتسجيل البيانات بسهولة ومشاركتها.
  2. أتمتة سير العمل: مع وظائف DigitalOcean ومشغلات الجدولة، قمت بأتمتة العمليات وجعلت تطبيقاتك تعمل بسلاسة.
  3. إضافة الذكاء إلى تطبيقاتك: من خلال تكامل GenAI من DigitalOcean، جلبت استخراج البيانات الذكي وتنظيمها إلى سير العمل الخاص بك، مما جعل تطبيقاتك أكثر ذكاءً وقدرة.
  4. التعامل مع الملفات بأمان: عملت مع مساحات DigitalOcean لتخزين وإدارة الملفات بطريقة موثوقة وقابلة للتوسع.
  5. تعزيز التطبيقات باستخدام واجهات برمجة التطبيقات: جلبت واجهات برمجة التطبيقات مثل Twilio، وPostmark، وResend وظائف مثل إشعارات SMS، وإعادة توجيه البريد الإلكتروني، ورسائل التأكيد إلى تطبيقاتك.
  6. تصحيح الأخطاء والرصد: باستخدام أدوات مثل Papertrail، تعلمت كيفية تصحيح الأخطاء ومراقبة تطبيقاتك بفعالية، لتبقيها تعمل بسلاسة.

الخطوة التالية

هذا هو مجرد البداية – ما تعلمته هنا يمكن تطبيقه على العديد من المشاريع الأخرى. فيما يلي بعض الطرق للمضي قدمًا:

إذا قمت بمتابعتنا، سررت لرؤية ما تقوم بإنشائه – لا تتردد في مشاركة تقدمك أو تعليقاتك معي على تويتر.

ابق الأمور بسيطة. قم ببناء شيء مفيد. نتمنى لك بناء ممتع! 🚀

Source:
https://www.digitalocean.com/community/tutorials/sending-confirmation-emails-with-resend