إرسال رسائل البريد الإلكتروني عبر SMTP باستخدام PHPMailer — دليل لتطبيق PHP مخصص

مقدمة

PHPMailer هي مكتبة PHP مستخدمة على نطاق واسع لإرسال رسائل البريد الإلكتروني عبر SMTP (Simple Mail Transfer Protocol). بالمقارنة مع الدالة الأصلية mail() mail()، فإن PHPMailer يسهل المصادقة والتشفير (STARTTLS / SMTPS)، وإضافة المرفقات، وإظهار تقارير أخطاء مفصّلة. يشرح هذا الدليل خطوة بخطوة كيفية إعداد حساب cPanel ودمج PHPMailer في تطبيق PHP مخصص.

المتطلبات

• عنوان بريد إلكتروني صالح على استضافتك (مثال: nom@votredomaine.tld nom@votredomaine.tld). انظر «كيف أنشئ عنوان بريد إلكتروني في حسابي على cPanel؟» (مقالة cPanel).
• بيانات اعتماد SMTP: المضيف (hostname)، المنفذ (عادةً 587 أو 465)، اسم المستخدم (غالبًا عنوان البريد الإلكتروني الكامل) وكلمة المرور.
• سجلات DNS لتحسين التسليم: تفعيل SPF و DKIM للنطاق. استخدم أداة Email Deliverability في cPanel للتشخيص (مقالة cPanel) وراجع أيضًا SPF و DKIM.
• PHP (يوصى باستخدام إصدار حديث) مع امتدادات مفيدة: openssl openssl (لـ TLS)، mbstringmbstring، إلخ. تحقّق من الإصدار والامتدادات عبر MultiPHP/Selector في cPanel إذا لزم الأمر.
• طريقة تثبيت PHPMailer: Composer (مستحسن) أو التثبيت اليدوي (رفع الملفات src/ src/ و vendor/ vendor/ إذا قمت بالتثبيت محليًا).

ملخص سريع للخطوات

1. إنشاء صندوق البريد الإلكتروني في cPanel.
2. التحقق من SPF/DKIM وتوجيه رسائل البريد الإلكتروني.
3. تثبيت PHPMailer (Composer أو يدوي).
4. أضف سكربت اختبار PHP وقم بضبط إعدادات SMTP.
5. اختبر، تحقق من تسليم الرسائل واستكشاف الأخطاء وإصلاحها عند الحاجة.

الخطوة 1 — إنشاء صندوق بريد إلكتروني في cPanel

إذا لم يكن لديك بعد عنوان مخصص للإرسال، فأنشئ واحدًا في حسابات البريد الإلكتروني في cPanel. احتفظ بالعنوان وكلمة المرور؛ ستحتاجهما للمصادقة عبر SMTP.

الخطوة 2 — التحقق من قابلية التسليم والتوجيه

قبل الإرسال المنتظم، تحقق من أن سجلات SPF و DKIM مكوّنة لنطاقك — هذا يقلل من خطر تصنيف رسائلك كبريد مزعج. في cPanel، افتح Email Deliverability للحصول على تشخيص والسجلات الموصى بها.

إذا كنت تستخدم خدمة SMTP خارجية (Gmail، Office365، Mailgun، إلخ)، فاتبع تعليمات المزود (المنافذ، التشفير، كلمات مرور التطبيقات أو OAuth2). كما تأكّد أن سجلات MX وتوجيه البريد الإلكتروني متوافقة مع المزود المختار.

الخطوة 3 — تثبيت PHPMailer

Composer هي الطريقة الموصى بها. إذا لم يتوفر Composer على الخادم، فثبّت PHPMailer محليًا ثم ارفع المجلد vendor/ أو استخدم التثبيت اليدوي.

الخيار أ — باستخدام Composer (موصى به)

1. تحقق من توفر Composer (عبر SSH أو من خلال Terminal في cPanel):

   composer --version

2. من مجلد تطبيقك (مثلاً public_html/monapp/) نفّذ:

   composer require phpmailer/phpmailer

3. على الخادم، قم بعد ذلك بتضمين ملف autoload في السكربتات الخاصة بك:

   require __DIR__ . '/vendor/autoload.php';

إذا لم تتمكن من تشغيل Composer على الخادم: قم بتشغيل composer require phpmailer/phpmailer على جهازك المحلي، ثم ارفع المجلد vendor/ وملفات تطبيقك إلى الخادم (عبر FTP أو مدير الملفات).

الخيار B — التثبيت اليدوي

1. حمّل أرشيف PHPMailer من المستودع الرسمي (ملف ZIP)، واستخرج المجلد src/.
2. ضع المجلدات اللازمة ("src/") في مجلد تطبيقك وقم بتضمين الملفات مباشرة:

   require 'PHPMailer/src/Exception.php';
   require 'PHPMailer/src/PHPMailer.php';
   require 'PHPMailer/src/SMTP.php';
   

3. إذا قمت بإنشاء المجلد محليًا vendor/، فاستخدم مدير الملفات في cPanel أو FTP لرفعه (مثلاً ارفع ملف .zip واستخرجه على الخادم).

الخطوة 4 — مثال على سكربت PHP (تكوين SMTP)

مثال مصغر (PHPMailer v6+، التثبيت عبر Composer) — عدّل القيم Host، Username، Port و Password :

<?php
require __DIR__ . '/vendor/autoload.php';

use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\Exception;
use PHPMailer\PHPMailer\SMTP;

$mail = new PHPMailer(true);
try {
    // Paramètres SMTP
    $mail->isSMTP();
    $mail->Host       = 'smtp.votredomaine.tld';
    $mail->SMTPAuth   = true;
    $mail->Username   = 'nom@votredomaine.tld';
    $mail->Password   = getenv('SMTP_PASS'); // ou récupéré depuis un fichier de config hors public_html
    $mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS; // ou PHPMailer::ENCRYPTION_SMTPS
    $mail->Port       = 587; // 587 (STARTTLS) ou 465 (SMTPS)

    // Destinataires et contenu
    $mail->setFrom('nom@votredomaine.tld', 'Nom affiché');
    $mail->addAddress('destinataire@example.com', 'Nom destinataire');
    $mail->isHTML(true);
    $mail->Subject = 'Sujet du message';
    $mail->Body    = '
Bonjour, ceci est un message de test.
';
    $mail->AltBody = 'Bonjour, ceci est un message de test.';

    $mail->send();
    echo 'Message envoyé';
} catch (Exception $e) {
    // n'affichez pas les mots de passe en production
    error_log('PHPMailer Error: ' . $mail->ErrorInfo);
    echo 'Erreur d\'envoi : ' . $mail->ErrorInfo;
}

خيارات مفيدة لتصحيح الأخطاء

للحصول على تتبع SMTP (لا تُفعّل في بيئة الإنتاج):

$mail->SMTPDebug = SMTP::DEBUG_SERVER; // sorties détaillées
$mail->Debugoutput = function($str, $level) {
    error_log('PHPMailer SMTP: ' . $str);
};

حالة خاصة: شهادات TLS/SSL في بيئة التطوير

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

$mail->SMTPOptions = [
  'ssl' => [
    'verify_peer'       => false,
    'verify_peer_name'  => false,
    'allow_self_signed' => true,
  ],
];

الخطوة 5 — اختبار والتحقق من التسليم

1. شغّل البرنامج النصي من المتصفّح (مثلاً https://votredomaine.tld/monapp/test-mail.php) أو من سطر الأوامر (php test-mail.php).
2. إذا فشل الإرسال، فعّل تصحيح أخطاء PHPMailer واطّلع على سجلات PHP/الخادم (الأخطاء وتتبعات SMTP).
3. استخدم الأداة Track Delivery من cPanel لتتبع مسار الرسالة وقراءة رموز الخطأ التي تُرجعها الخوادم البعيدة.

استكشاف الأخطاء الشائعة (موجز)

1. "SMTP connect() failed" / رفض الاتصال
   • تحقق من Host، Port و SMTPSecure (STARTTLS على 587، SMTPS على 465).
   • اختبار الاتصال من جهازك:

     telnet smtp.votredomaine.tld 587
     # ou
     openssl s_client -starttls smtp -connect smtp.votredomaine.tld:587

   • في الاستضافة المشتركة، قد تُقيَّد بعض اتصالات SMTP الصادرة؛ اتصل بالدعم إذا لزم الأمر.
2. فشل المصادقة
   • تحقق من أن اسم المستخدم هو عنوان البريد الإلكتروني الكامل وأن كلمة المرور صحيحة (لا توجد مسافة في نهاية السلسلة).
   • في حال استخدام Gmail أو Office365، فعّل كلمة مرور للتطبيق أو OAuth2 إذا تطلّب المزود ذلك.
3. رفض من جانب المستلم / تصنيف الرسالة كبريد غير مرغوب فيه.
   • راجع رمز الخطأ الذي أعاده خادم الجهة المستقبِلة (عبر Track Delivery أو سجلات SMTP).
   • تأكد من أن سجلات SPF وDKIM منشورة بشكل صحيح وأن سجل DMARC مُعدّ بشكل مناسب.
4. خطأ في شهادة TLS
   • تحقّق من أن خادم SMTP يقدّم سلسلة شهادات صالحة. في بيئة التطوير فقط يمكنك تخفيف التحقق (انظر SMTPOptions)، لكن أصلح السلسلة في بيئة الإنتاج.
5. مرفقات مفقودة
   • تحقّق من مسارات الملفات والأذونات وحدود الرفع التي يفرضها المُستضيف.

أفضل الممارسات

• لا تخزن كلمات المرور كنص واضح داخل سكربت عام. ضع التكوين خارج <code>public_html</code> public_html أو استخدم متغيرات البيئة (<code>getenv()</code>).getenv()).
• فعّل وتحقق من سجلات SPF وDKIM لتحسين قابلية تسليم الرسائل.
• عطّل تصحيح أخطاء SMTP التفصيلي في بيئة الإنتاج (قد يحتوي على كلمات مرور).
• بالنسبة للإرسالات الكبيرة (نشرات إخبارية، إشعارات جماعية)، فضّل استخدام خدمة إرسال مخصصة (SMTP relay) التي تدير الحصص وسمعة الإرسال.

القيود والنقاط الواجب التحقق منها

• في باقات الاستضافة المشتركة، قد يُحظر أو يُقيّد الإرسال الصادر عبر المنفذ 25 أو منافذ أخرى؛ تحقق مع المُستضيف.
• بعض المزودين — مثل Gmail وOffice365 — يتطلبون OAuth2؛ ويتطلب تكامل OAuth2 خطوات إضافية (مكتبات وإعدادات).
• قد تُطبّق حصص الإرسال (رسائل/ساعة) على مستوى الخادم: تحقق من سياسة المُستضيف إذا كنت تخطط لحجم كبير.

قائمة التحقق قبل النشر في بيئة الإنتاج

• تم إنشاء صندوق البريد الإلكتروني والتحقق من بيانات الاعتماد.
• تم تكوين سجلات SPF وDKIM ونتيجة التشخيص سليمة.
• تم تثبيت PHPMailer وتعمل آلية التحميل التلقائي (autoload).
• تم اختبار السكربت في بيئة ما قبل الإنتاج؛ سجلات تصحيح الأخطاء محفوظة خارج الموقع العام.
• آلية مؤمّنة لتغيير/تدوير كلمات المرور.

موارد داخلية مفيدة

• كيف أنشئ عنوان بريد إلكتروني في حساب cPanel الخاص بي؟
• كيف أستخدم ميزة Email Deliverability في cPanel؟
• SPF و DKIM: كيف أحسّن سمعة رسائل البريد الإلكتروني المرسلة عبر cPanel؟
• تتبع التسليم: كيف تتتبّع رسائل البريد الإلكتروني الخاصة بك في cPanel؟

إذا استمرّت المشكلة، افتح تذكرة من مساحة العميل الخاصة بك وأرفق مخرجات تصحيح الأخطاء الخاصة بـ PHPMailer (ملاحظة: احذف كلمات المرور قبل المشاركة) واذكر وقت الاختبار حتى يتمكن فريق الدعم من مراجعة سجلات الخادم.

تمّت مراجعة الوثائق في 17 أكتوبر 2026. قد تختلف الأدوات حسب مزوّد الاستضافة.