تعد إشعارات البريد الإلكتروني أمرًا بالغ الأهمية لتطبيقات الويب الحديثة. في هذا الدليل، سنقوم بإنشاء خدمة إشعارات بريد إلكتروني آمنة باستخدام Express.js ومصادقة OAuth2 الخاصة بـ Gmail. ستقبل خدمتنا طلبات webhook وترسل رسائل البريد الإلكتروني تلقائيًا بناءً على البيانات الواردة.

ما نقوم ببنائه

سنقوم بإنشاء خادم سريع يقوم بما يلي:

• يتلقى بيانات الرد التلقائي عبر الويب عبر طلبات POST
• المصادقة مع Gmail باستخدام OAuth2
• يرسل رسائل بريد إلكتروني مخصصة بناءً على حمولة خطاف الويب
• يتعامل مع الأخطاء بأمان

المتطلبات الأساسية

• تم تثبيت Node.js على جهازك
• تم تمكين مشروع Google Cloud Console مع Gmail API
• بيانات اعتماد OAuth2 (معرف العميل، سر العميل، رمز التحديث)
• الفهم الأساسي لـ Express.js وasync/await

إعداد المشروع

أولاً، قم بتثبيت الحزم المطلوبة:

npm install express body-parser nodemailer googleapis dotenv

قم بإنشاء ملف .env باستخدام بيانات الاعتماد الخاصة بك:

CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
REDIRECT_URI=your_redirect_uri
REFRESH_TOKEN=your_refresh_token
[email protected]

إذا واجهت أي صعوبات في إعداد بيانات الاعتماد هذه، كما فعلت أنا، فيمكنك اتباع الخطوات أدناه...

الخطوة 1: إنشاء مشروع Google Cloud جديد:

أ. انتقل إلى https://console.cloud.google.com/
ب. انقر على القائمة المنسدلة للمشروع في أعلى الصفحة
ج. انقر على "مشروع جديد"
د. أدخل اسم المشروع وانقر على "إنشاء"

الخطوة 2: تمكين واجهة برمجة تطبيقات Gmail:
أ. في الشريط الجانبي الأيسر، انتقل إلى "واجهات برمجة التطبيقات والخدمات" > "المكتبة"
ب. البحث عن "Gmail API"
ج. انقر على "Gmail API" ثم انقر على "تمكين"

الخطوة 3: تكوين شاشة موافقة OAuth:
أ. انتقل إلى "واجهات برمجة التطبيقات والخدمات" > "شاشة موافقة OAuth"
ب. اختر "خارجي" كنوع المستخدم وانقر على "إنشاء"
ج. املأ الحقول المطلوبة:
- اسم التطبيق: [اسم تطبيقك]
- البريد الإلكتروني لدعم المستخدم: [بريدك الإلكتروني]
- معلومات الاتصال بالمطور: [بريدك الإلكتروني]
د. انقر على "حفظ ومتابعة"
ه. في صفحة "النطاقات"، انقر فوق "إضافة أو إزالة النطاقات"
و. ابحث عن نطاق "https://mail.google.com/" وحدده
ز. انقر على "تحديث" ثم "حفظ ومتابعة"
ح. في صفحة "اختبار المستخدمين"، انقر على "إضافة مستخدمين"
أنا. أضف عنوان Gmail الخاص بك وانقر على "حفظ ومتابعة"
ي. قم بمراجعة الملخص ثم انقر على "الرجوع إلى لوحة التحكم"

الخطوة 4: إنشاء بيانات اعتماد OAuth2:
أ. انتقل إلى "واجهات برمجة التطبيقات والخدمات" > "بيانات الاعتماد"
ب. انقر على "إنشاء بيانات اعتماد" > "معرف عميل OAuth"
ج. اختر "تطبيق الويب" كنوع التطبيق
د. الاسم: [اسم التطبيق الخاص بك]
ه. أصول JavaScript المعتمدة: أضف مجال الخادم الخاص بك (على سبيل المثال، http://localhost:3000 للتطوير المحلي)

و. عناوين URL لإعادة التوجيه المعتمدة:
- إضافة: https://developers.google.com/oauthplayground
- أضف عنوان URL لرد الاتصال الخاص بخادمك إذا كان لديك واحدًا (على سبيل المثال، http://localhost:3000/auth/google/callback)
ز. انقر فوق "إنشاء"
ح. ستظهر نافذة منبثقة معرِّف العميل وسر العميل. احفظها بشكل آمن.

الخطوة 5: احصل على رمز التحديث الجديد:
أ. انتقل إلى https://developers.google.com/oauthplayground/

ب. انقر على أيقونة الترس (مثل الإعدادات) في الزاوية اليمنى العليا
ج. انقر فوق مربع الاختيار "استخدام بيانات اعتماد OAuth الخاصة بك"
د. أدخل معرف العميل الجديد وسر العميل
ه. إغلاق الإعدادات
و. في الشريط الجانبي الأيسر، ابحث عن "Gmail API v1"
ز. حدد https://mail.google.com/
ح. انقر على "تخويل واجهات برمجة التطبيقات"
أنا. اختر حسابك في Google وامنح الأذونات المطلوبة
ي. في الشاشة التالية، انقر على "رمز ترخيص التبادل للرموز المميزة"
ك. انسخ "رمز التحديث" من الرد

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

وأوضح الكود

دعونا نقسم التنفيذ خطوة بخطوة:

1. الإعداد الأولي والتبعيات

const express = require("express");
const bodyParser = require("body-parser");
const nodemailer = require("nodemailer");
const { google } = require("googleapis");
require("dotenv").config();

const app = express();
app.use(bodyParser.json());

يقوم هذا القسم بإعداد خادم Express الخاص بنا واستيراد التبعيات الضرورية. نستخدم محلل الجسم لتحليل طلبات JSON وdotenv لإدارة متغيرات البيئة.

2. تكوين OAuth2

const oAuth2Client = new google.auth.OAuth2(
  CLIENT_ID,
  CLIENT_SECRET,
  REDIRECT_URI
);
oAuth2Client.setCredentials({ refresh_token: REFRESH_TOKEN });

نقوم بإنشاء عميل OAuth2 باستخدام مكتبة مصادقة Google. يعالج هذا تحديث الرمز المميز والمصادقة باستخدام واجهة برمجة تطبيقات Gmail.

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

async function sendEmail(webhookData) {
  const {
    receiver_email, //change data based on your needs
  } = webhookData;

  try {
    const accessToken = await oAuth2Client.getAccessToken();
    const transport = nodemailer.createTransport({
      service: "gmail",
      auth: {
        type: "OAuth2",
        user: process.env.EMAIL_USER,
        clientId: CLIENT_ID,
        clientSecret: CLIENT_SECRET,
        refreshToken: REFRESH_TOKEN,
        accessToken: accessToken,
      },
    });

    const mailOptions = {
      from: `Your Name `,
      to: receiver_email,
      subject: ``, //Add Subject of Email
      html: ``, // Add your HTML template here
    };

    return await transport.sendMail(mailOptions);
  } catch (error) {
    console.error("Error in sendMail function:", error);
    throw error;
  }
}

هذه الوظيفة:

• استخراج البيانات من حمولة خطاف الويب، ويمكنك تعديل الحمولة بناءً على الاحتياجات
• الحصول على رمز وصول جديد
• إنشاء وسيلة نقل باستخدام مصادقة OAuth2
• يرسل البريد الإلكتروني بمحتوى مخصص

4. نقطة نهاية Webhook

app.post("/webhook", async (req, res) => {
  try {
    const webhookData = req.body;
    await sendEmail(webhookData);
    res.status(200).send("Email sent successfully");
  } catch (error) {
    console.error("Error processing webhook:", error);
    res.status(500).send("Error processing webhook");
  }
});

نقطة نهاية خطاف الويب الخاص بنا:

• يتلقى طلبات POST
• يعالج بيانات الرد التلقائي على الويب
• يرسل رسائل البريد الإلكتروني
• إرجاع الاستجابات المناسبة

اختبار

اختبر خطاف الويب الخاص بك باستخدام Curl أو Postman:

curl -X POST http://localhost:4000/webhook \
-H "Content-Type: application/json" \
-d '{
  "receiver_email": "[email protected]",
}'

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

المشكلات والحلول الشائعة:

1. أخطاء المصادقة: التحقق من بيانات اعتماد OAuth2
2. انتهاء صلاحية الرمز المميز: تأكد من صلاحية رمز التحديث
3. البيانات المفقودة: التحقق من صحة حمولة خطاف الويب

خاتمة

لديك الآن نظام إشعارات آمن عبر البريد الإلكتروني OAuth2! يوفر هذا التنفيذ أساسًا متينًا لبناء أنظمة إعلام أكثر تعقيدًا مع الحفاظ على الأمان والموثوقية.

آمل أن يكون هذا المنشور مفيدًا لك لإعداد خدمة البريد الإلكتروني.

ترميز سعيد! ?