درس تعليمي 7 دقائق قراءة آخر تحديث أبريل ٢٠٢٦

إرسال البريد التحويلي مع Node.js (مع أمثلة كود)

نهجان: REST API الخاص بـ Emitlo (موصى به للمشاريع الجديدة) وNodemailer + SMTP (لقواعد الكود الموجودة). كلاهما يستخدم Emitlo كبنية تحتية للإرسال.

هذه الأمثلة تستخدم API الخاص بـ Emitlo. سجّل مجاناً للمتابعة — 12,000 رسالة/شهر، بدون بطاقة ائتمان.

الطريقة 1: REST API لـ Emitlo (fetch)

النهج الأبسط — لا تبعيات مطلوبة. يعمل في Node.js 18+ مع fetch API الأصلي.

// send-email.js
const response = await fetch('https://api.emitlo.com/v1/messages', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.EMITLO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: 'hello@نطاقك.com',
    to: '[email protected]',
    subject: 'مرحباً بك في تطبيقنا',
    html: '<h1>مرحباً!</h1><p>شكراً لتسجيلك.</p>',
    text: 'مرحباً! شكراً لتسجيلك.',
  }),
});

if (!response.ok) {
  const error = await response.json();
  throw new Error(`فشل البريد الإلكتروني: ${error.message}`);
}

const result = await response.json();
console.log('أُرسل:', result.id); // msg_8f2c...

الطريقة 2: REST API لـ Emitlo (axios)

// npm install axios
const axios = require('axios');

async function sendEmail({ to, subject, html, text }) {
  const { data } = await axios.post(
    'https://api.emitlo.com/v1/messages',
    { from: 'hello@نطاقك.com', to, subject, html, text },
    {
      headers: {
        Authorization: `Bearer ${process.env.EMITLO_API_KEY}`,
      },
    }
  );
  return data; // { id: 'msg_8f2c...', status: 'queued' }
}

// الاستخدام
await sendEmail({
  to: '[email protected]',
  subject: 'تم تأكيد طلبك',
  html: '<h1>الطلب #1234 مؤكد</h1>',
  text: 'الطلب #1234 مؤكد',
});

هذه الأمثلة تستخدم API الخاص بـ Emitlo. سجّل مجاناً للمتابعة →

الطريقة 3: Nodemailer + SMTP

استخدم هذا النهج إذا كان لديك قاعدة كود موجودة تستخدم Nodemailer. فقط حدّث بيانات اعتماد SMTP لاستخدام Emitlo.

// npm install nodemailer
const nodemailer = require('nodemailer');

const transporter = nodemailer.createTransport({
  host: 'smtp.emitlo.com',
  port: 587,
  secure: false, // استخدم STARTTLS
  auth: {
    user: process.env.EMITLO_SMTP_USER,
    pass: process.env.EMITLO_SMTP_PASS,
  },
});

async function sendEmail({ to, subject, html, text }) {
  const info = await transporter.sendMail({
    from: '"تطبيقك" <hello@نطاقك.com>',
    to,
    subject,
    html,
    text,
  });
  return info.messageId;
}

// الاستخدام
await sendEmail({
  to: '[email protected]',
  subject: 'إعادة تعيين كلمة المرور',
  html: '<p>انقر <a href="...">هنا</a> لإعادة تعيين كلمة مرورك.</p>',
  text: 'زر هذا الرابط لإعادة تعيين كلمة مرورك: ...',
});

إرسال بريد HTML

أدرج دائماً نسختَي HTML والنص العادي. بعض عملاء البريد الإلكتروني يعرضون النص العادي افتراضياً، وفلاتر البريد العشوائي تبحث عن وجود نسخة نص عادي.

const emailHtml = `
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body style="font-family: sans-serif; max-width: 600px; margin: 0 auto; padding: 20px;">
  <h1 style="color: #1a1a2e;">مرحباً بك في تطبيقنا</h1>
  <p>مرحباً ${user.name}،</p>
  <p>شكراً لتسجيلك. انقر على الزر أدناه للتحقق من بريدك الإلكتروني.</p>
  <a href="${verifyUrl}" 
     style="display: inline-block; background: #6c3ff9; color: white; 
            padding: 12px 24px; border-radius: 8px; text-decoration: none;">
    تحقق من البريد الإلكتروني
  </a>
</body>
</html>
`;

const emailText = `
مرحباً بك في تطبيقنا

مرحباً ${user.name}،

شكراً لتسجيلك. زر هذا الرابط للتحقق من بريدك الإلكتروني:
${verifyUrl}
`;

إرسال مع مرفقات

// REST API مع مرفق
const fs = require('fs');
const pdfBuffer = fs.readFileSync('./invoice.pdf');

await fetch('https://api.emitlo.com/v1/messages', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.EMITLO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: 'billing@نطاقك.com',
    to: '[email protected]',
    subject: 'فاتورتك #INV-1234',
    html: '<p>يرجى الاطلاع على فاتورتك المرفقة.</p>',
    text: 'يرجى الاطلاع على فاتورتك المرفقة.',
    attachments: [{
      filename: 'invoice-1234.pdf',
      content: pdfBuffer.toString('base64'),
      contentType: 'application/pdf',
    }],
  }),
});

معالجة الأخطاء

async function sendEmailSafe({ to, subject, html, text }) {
  try {
    const response = await fetch('https://api.emitlo.com/v1/messages', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.EMITLO_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ from: 'hello@نطاقك.com', to, subject, html, text }),
    });

    if (response.status === 429) {
      // تجاوز حد المعدل — أعد المحاولة بعد تأخير
      const retryAfter = response.headers.get('Retry-After') || 60;
      throw new Error(`تجاوز حد المعدل. أعد المحاولة بعد ${retryAfter}s`);
    }

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`خطأ API البريد الإلكتروني ${response.status}: ${error.message}`);
    }

    return await response.json();
  } catch (err) {
    // سجّل الخطأ مع السياق للتصحيح
    console.error('فشل إرسال البريد الإلكتروني', { to, subject, error: err.message });
    throw err; // أعد الإطلاق ليتعامل معه المستدعي
  }
}

متغيرات البيئة

لا تُشفّر مفاتيح API مباشرة. استخدم متغيرات البيئة:

# .env
EMITLO_API_KEY=your_api_key_here
EMITLO_SMTP_USER=your_smtp_user
EMITLO_SMTP_PASS=your_smtp_password
EMAIL_FROM=hello@نطاقك.com

// تحميل مع dotenv
require('dotenv').config();
const apiKey = process.env.EMITLO_API_KEY;

ابدأ إرسال البريد التحويلي في Node.js — مجاناً

12,000 رسالة/شهر (400/يوم) · REST API + SMTP · بدون بطاقة ائتمان

احصل على مفتاح API الخاص بك → See all comparisons

الأسئلة الشائعة

ما هي أفضل طريقة لإرسال البريد التحويلي في Node.js؟

للمشاريع الجديدة، استخدم REST API (مثل API الخاص بـ Emitlo) مع fetch API الأصلي أو axios. للمشاريع الموجودة التي تستخدم Nodemailer، هيّئه ببيانات اعتماد SMTP الخاصة بـ Emitlo. نهج REST API يمنح معالجة أفضل للأخطاء واستجابات منظمة.

هل يجب استخدام Nodemailer أم REST API للبريد التحويلي؟

كلاهما يعمل بشكل جيد. Nodemailer + SMTP أسهل في التكامل مع قواعد الكود الموجودة. REST API يمنح معالجة أفضل للأخطاء واستجابات منظمة ويُفضَّل للتطبيقات الجديدة. Emitlo تدعم كليهما بنفس بيانات الاعتماد وحدود المعدل.

كيف أتعامل مع أخطاء البريد الإلكتروني في Node.js؟

دائماً لفّ إرسال البريد الإلكتروني في try/catch. تحقق من رمز حالة HTTP لاستدعاءات REST API (200 = نجاح، 4xx = خطأ عميل، 5xx = خطأ خادم). لـ SMTP، يُطلق Nodemailer أخطاء لإخفاقات الاتصال والرسائل المرفوضة. سجّل الأخطاء مع سياق كافٍ للتصحيح (المستلم والموضوع ورسالة الخطأ).

كيف أرسل بريداً إلكترونياً HTML في Node.js؟

مرّر سلسلة HTML الخاصة بك كخاصية html في جسم الطلب (REST API) أو خيار html في Nodemailer. أدرج دائماً بديلاً بنص عادي (خاصية text) لعملاء البريد الإلكتروني الذين لا يُصيّرون HTML.

كيف أرسل بريداً إلكترونياً مع مرفقات في Node.js؟

مع REST API الخاص بـ Emitlo، أدرج مصفوفة attachments في جسم الطلب مع محتوى الملف المُشفَّر بـ base64. مع Nodemailer، استخدم خيار attachments مع path أو content أو buffer. الخطة المجانية لـ Emitlo تدعم المرفقات حتى 10 ميغابايت.