كيفية استخدام Nodemailer لإرسال رسائل البريد الإلكتروني من خادم Node.js

مقدمة: لماذا تستخدم Nodemailer في تطبيقات Node.js؟

تُعد مكتبة Nodemailer واحدة من أشهر الأدوات المخصصة لإرسال رسائل البريد الإلكتروني من تطبيقات Node.js. وتبرز أهميتها عندما تحتاج إلى إرسال رسائل ترحيبية للمستخدمين، أو تنبيهات خاصة بالنظام، أو إشعارات تلقائية عند حدوث خطأ داخل الخادم.

في هذا الدليل، سنشرح طريقة عملية واحترافية لاستخدام Nodemailer مع Gmail داخل بيئة Node.js بالاعتماد على OAuth2، وهي الطريقة الأكثر أمانًا وملاءمة للتطبيقات الحديثة.

البدء بإعداد مشروع Node.js

قبل تثبيت Nodemailer، من الأفضل تجهيز مشروع بسيط باستخدام Express حتى نمتلك خادمًا جاهزًا للتجربة.

التحقق من تثبيت Node.js وnpm

نفّذ الأوامر التالية داخل الطرفية للتأكد من أن البيئة جاهزة:

node -v
npm -v

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

إنشاء مجلد المشروع وتهيئته

أنشئ مجلدًا جديدًا للمشروع، ثم ادخل إليه وابدأ تهيئة الحزمة:

mkdir nodemailerProject
cd nodemailerProject
npm init

سيؤدي ذلك إلى إنشاء ملف package.json الذي يدير إعدادات المشروع واعتمادياته.

تثبيت Express

npm install express

بعد ذلك، افتح ملف نقطة الدخول مثل index.js وأضف الكود التالي:

const express = require('express')
const app = express()
const port = 3000

app.listen(port, () => {
  console.log(`nodemailerProject is listening at http://localhost:${port}`)
})

لتشغيل الخادم:

node index.js

إذا ظهر الرابط في الطرفية، فهذا يعني أن الخادم يعمل بشكل صحيح.

تثبيت مكتبة Nodemailer

الآن يمكننا تثبيت المكتبة الأساسية المسؤولة عن إرسال البريد:

npm install nodemailer

تعتمد آلية العمل في Nodemailer غالبًا على 3 خطوات رئيسية:

• إنشاء كائن Transporter.
• إنشاء كائن mailOptions.
• استخدام الدالة sendMail() لإرسال الرسالة.

إعداد Transporter للاتصال بخدمة Gmail

الجزء الأهم هو إنشاء كائن الاتصال الذي يتولى تمرير بيانات المصادقة إلى Gmail. إليك الصيغة الأساسية:

let transporter = nodemailer.createTransport({
  service: 'gmail',
  auth: {
    type: 'OAuth2',
    user: process.env.MAIL_USERNAME,
    pass: process.env.MAIL_PASSWORD,
    clientId: process.env.OAUTH_CLIENTID,
    clientSecret: process.env.OAUTH_CLIENT_SECRET,
    refreshToken: process.env.OAUTH_REFRESH_TOKEN
  }
});

لاحظ أن الحقول user وpass تمثل بيانات حساب Gmail، بينما تتطلب الحقول clientId وclientSecret وrefreshToken إعداد OAuth2 داخل منصة Google Cloud Platform.

هذه الخطوة ضرورية لأن Gmail يفرض قيودًا أمنية عالية على التطبيقات التي تحاول إرسال البريد نيابة عن المستخدم.

إعداد Google Cloud Platform لاستخدام OAuth2

إذا لم يكن لديك حساب على Google Cloud Platform، فابدأ بإنشائه. بعد ذلك، أنشئ مشروعًا جديدًا من القائمة العلوية.

اختر اسمًا مناسبًا للمشروع، ويمكنك مثلًا استخدام NodemailerProject.

بعد اكتمال إنشاء المشروع، انتقل إلى قسم APIs and Services من القائمة الجانبية.

تهيئة شاشة الموافقة الخاصة بـ OAuth Consent Screen

حتى تتمكن من استخدام OAuth2، عليك أولًا إعداد شاشة الموافقة الخاصة بالتطبيق.

إذا لم تكن تستخدم G-Suite، فسيكون الخيار المتاح غالبًا هو External.

بعد ذلك، املأ بيانات التطبيق، وأضف بريدك الإلكتروني في حقلي دعم المستخدم وبيانات المطور.

يمكنك تجاوز قسم Scopes في هذا السيناريو، ثم الانتقال إلى قسم Test Users وإضافة بريدك الإلكتروني كمستخدم تجريبي.

إنشاء بيانات اعتماد OAuth Client ID

بعد إعداد شاشة الموافقة، انتقل إلى تبويب Credentials، ثم اختر Create Credentials وبعدها OAuth Client ID.

من نوع التطبيق اختر Web Application.

داخل قسم Authorized Redirect URIs، أضف الرابط التالي لأنه سيُستخدم لاحقًا للحصول على refreshToken:

https://developers.google.com/oauthplayground

بعد الإنشاء، ستحصل على clientId وclientSecret. احتفظ بهما في مكان آمن جدًا، ولا تشاركهما علنًا مطلقًا.

الحصول على OAuth Refresh Token

الآن نحتاج إلى استخراج refreshToken، وهو جزء أساسي في مصادقة Nodemailer مع Gmail.

انتقل إلى OAuth2 Playground، ثم اضغط على رمز الترس وفعّل خيار استخدام بيانات OAuth2 الخاصة بك.

من القائمة الجانبية، ابحث عن Gmail API v1.

بعد الضغط على Authorize APIs، سجّل الدخول بالحساب الذي أضفته كمستخدم تجريبي. قد تظهر رسالة تفيد بأن التطبيق غير موثّق بعد، ويمكنك المتابعة لأنك لم تُرسله بعد للمراجعة.

بعد منح الصلاحية للتطبيق للوصول إلى حساب Gmail:

ستعود إلى صفحة OAuth Playground وبإمكانك الضغط على Exchange authorization code for tokens للحصول على accessToken وrefreshToken.

العودة إلى المشروع وتأمين البيانات السرية

بعد جمع القيم المطلوبة، من الأفضل عدم كتابتها مباشرة داخل الشيفرة. استخدم حزمة dotenv لتخزين البيانات الحساسة داخل ملف .env.

npm install dotenv

ولا تنسَ إضافة ملف .env إلى ملف .gitignore حتى لا يتم رفعه إلى المستودع.

صيغة transporter بعد استخدام المتغيرات البيئية

let transporter = nodemailer.createTransport({
  service: 'gmail',
  auth: {
    type: 'OAuth2',
    user: process.env.MAIL_USERNAME,
    pass: process.env.MAIL_PASSWORD,
    clientId: process.env.OAUTH_CLIENTID,
    clientSecret: process.env.OAUTH_CLIENT_SECRET,
    refreshToken: process.env.OAUTH_REFRESH_TOKEN
  }
});

إنشاء كائن mailOptions

هذا الكائن يحتوي على تفاصيل الرسالة: المرسل، والمستلم، والعنوان، والنص.

let mailOptions = {
  from: 'tomerpacific@gmail.com',
  to: 'tomerpacific@gmail.com',
  subject: 'Nodemailer Project',
  text: 'Hi from your nodemailer project'
};

يمكنك لاحقًا توسيع هذا الكائن ليشمل:

• أكثر من مستلم.
• نسخة كربونية cc.
• نسخة مخفية bcc.
• محتوى بصيغة HTML.
• مرفقات ملفات.

إرسال الرسالة عبر sendMail()

بعد إعداد كل شيء، تأتي الخطوة الأخيرة: استدعاء الدالة المسؤولة عن الإرسال.

transporter.sendMail(mailOptions, function(err, data) {
  if (err) {
    console.log('Error ' + err);
  } else {
    console.log('Email sent successfully');
  }
});

عند تشغيل التطبيق بنجاح، ستصل رسالة جديدة إلى صندوق البريد المحدد في الحقل to.

أفضل ممارسات عند استخدام Nodemailer مع Gmail

• لا تضع بيانات OAuth أو كلمات المرور داخل الشيفرة مباشرة.
• استخدم ملف .env مع حزمة dotenv.
• أضف ملف .env إلى .gitignore.
• اختبر عملية الإرسال باستخدام حساب تجريبي قبل الاعتماد على الخدمة في بيئة الإنتاج.
• راقب أخطاء الإرسال في السجلات لتتأكد من أن الإعدادات سليمة.

متى يكون هذا الأسلوب مناسبًا؟

يُعد هذا الأسلوب مناسبًا إذا كنت تبني:

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

لكن إذا كان مشروعك كبيرًا جدًا أو يعتمد على إرسال كثيف للبريد، فقد يكون من الأفضل التفكير في خدمات متخصصة مثل SendGrid أو Mailgun أو Amazon SES، لأنها تمنحك قابلية توسع ومراقبة أفضل.

الخلاصة التقنية

استخدام Nodemailer مع Node.js وGmail OAuth2 يوفّر طريقة موثوقة وآمنة لإرسال البريد الإلكتروني من الخادم دون تعريض بياناتك الحساسة للخطر. ورغم أن إعداد Google Cloud Platform قد يبدو طويلًا في البداية، إلا أنه يضمن تكاملًا أكثر أمانًا من الطرق التقليدية. إذا كنت تبحث عن حل عملي لمشاريع صغيرة ومتوسطة، فهذه المقاربة مناسبة جدًا، خاصة عند الالتزام بإدارة الأسرار عبر المتغيرات البيئية واتباع ضوابط الحماية الأساسية.