Nodemailer في JavaScript (Node.js): دليل شامل مع أمثلة

ما هو Nodemailer ولماذا تحتاجه؟

Nodemailer هو وحدة (module) خاصة بـ Node.js تتيح لك إرسال رسائل البريد الإلكتروني من تطبيق JavaScript الخاص بك. تُعتبر واحدة من أشهر وأكثر المكتبات استقرارًا في بيئة Node.js للتعامل مع الإيميلات. توفر واجهة برمجة تطبيقات (API) بسيطة لكنها قوية لإنشاء وإرسال الرسائل عبر وسائط نقل مختلفة (SMTP، Sendmail، Amazon SES وغيرها).

لماذا تحتاج Nodemailer؟

• أتمتة الإشعارات: إرسال رسائل التسجيل، إعادة تعيين كلمة المرور، تأكيد الطلبات، وغيرها من الأحداث.
• البريد الجماعي: إنشاء النشرات الإخبارية والحملات التسويقية (مع الحذر لتجنب البريد العشوائي).
• نماذج الاتصال: إرسال الرسائل من نماذج التواصل في موقعك.
• المراقبة والسجلات: إخطار المسؤول عن الأخطاء الحرجة في التطبيق.
• المرونة: دعم قوالب HTML، المرفقات، الصور المضمنة، وترميزات مختلفة.

يقوم Nodemailer بتجريد تعقيد العمل مع بروتوكولات البريد الإلكتروني (SMTP، POP3، IMAP) ويوفر واجهة موحدة وسهلة الفهم.

تثبيت Nodemailer

يتم تثبيت Nodemailer عبر مدير الحزم npm (Node Package Manager). تأكد من تثبيت Node.js (الإصدار 12 أو أحدث) على جهازك.

افتح الطرفية (Terminal) في المجلد الرئيسي لمشروعك ونفّذ الأمر التالي:

npm install nodemailer

بعد اكتمال التثبيت، يمكنك استيراد المكتبة إلى الكود الخاص بك:

const nodemailer = require('nodemailer');

للمشاريع التي تستخدم ES Modules (مع إضافة "type": "module" في ملف package.json)، استخدم الاستيراد التالي:

import nodemailer from 'nodemailer';

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

أسهل طريقة لإرسال بريد إلكتروني هي استخدام خادم SMTP. في هذا المثال، سنستخدم خدمة Gmail. هام: للعمل مع Gmail، ستحتاج إلى إنشاء "كلمة مرور للتطبيق" (App Password) أو استخدام OAuth2. كلمة المرور العادية للحساب لن تعمل بسبب إعدادات الأمان من Google.

const nodemailer = require('nodemailer');

// 1. إنشاء وسيلة النقل (طريقة الإرسال)
const transporter = nodemailer.createTransport({
    service: 'gmail',
    auth: {
        user: 'your-email@gmail.com', // بريدك الإلكتروني
        pass: 'your-app-password'     // كلمة مرور التطبيق
    }
});

// 2. إعداد البريد الإلكتروني
const mailOptions = {
    from: 'your-email@gmail.com',
    to: 'recipient@example.com',
    subject: 'مرحباً من Nodemailer!',
    text: 'هذه رسالة اختبارية تم إرسالها باستخدام Nodemailer.'
};

// 3. إرسال البريد الإلكتروني
transporter.sendMail(mailOptions, (error, info) => {
    if (error) {
        return console.log('خطأ:', error);
    }
    console.log('تم إرسال البريد:', info.messageId);
    console.log('رابط العرض:', nodemailer.getTestMessageUrl(info));
});

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

الطرق والوظائف الأساسية في Nodemailer

دعنا نستعرض بالتفصيل الطرق الرئيسية التي توفرها المكتبة.

1. nodemailer.createTransport(options)

الوظيفة: تنشئ كائن وسيلة النقل — وهو التكوين الأساسي الذي يحدد كيفية إرسال البريد الإلكتروني (عبر أي خادم وبأي بيانات اعتماد).

المعاملات:

• options (Object): كائن التكوين. الخصائص الأساسية:
  • host (String): عنوان خادم SMTP (مثال: 'smtp.gmail.com').
  • port (Number): منفذ الخادم (عادة 465 لـ SSL، 587 لـ TLS).