درس مصغّر · العربية

كيف ترسل رسائل بريد آلية من موقعك

شغّل مشروع البريد المرفق بمساعدة المساعد، وأرسل تأكيدًا تجريبيًا مضبوط الوجهة، وتحقق من وصوله إلى صندوقك.

ابدأ الدرس التفاعلياقرأ ملاحظات الدرس

لمن هذا الدرس؟

لمن يريدون إرسال بريد عند تنفيذ إجراء في الموقع. كود الخادم مرفق ويستطيع مساعد البرمجة ضبطه؛ لا تحتاج إلى كتابة نظام بريد خلفي.

قبل أن تبدأ

حسابك في Resend ومرسل موثّق وصندوق بريد تجريبي. استخدم مشروع دوال Netlify المنفصل كاملًا ومساعد برمجة لإعداده. تسري شروط توفر المزود واستخدامه. الإجابات المحلولة أمثلة توضيحية، وليست اختبارات أُجريت على حسابك. استبدل ملاحظاتها الافتراضية بنتائجك الفعلية، أو حدد الخطوة التي ما زالت متعذرة.

الوقت المتوقع: 21–38 دقيقة

تقديرات باستخدام ملفات البداية المرفقة، مع جاهزية الحسابات والأدوات المطلوبة. يستغرق الإعداد وانتظار النشر وتسليم البريد وتحديث DNS وقتًا إضافيًا. التحقق من المرسل وانتظار تسليم البريد وقت إضافي. تعتمد رسوم المزوّد وحدوده على الحساب.

ما الذي ستتعلمه؟

  • اضبط مرسلًا ومستلمًا تتحكم بهما.
  • شغّل إرسال بريد تجريبي حقيقي وافحص تسليمه.
  • تعامل مع الطلبات الفاشلة دون الإيهام بوصول رسالة.

ملفات ورشة العمل

الخطوة 1

اختر إجراءً واحدًا لإرسال البريد

ابدأ برسالة تأكيد ثابتة ومضبوطة الوجهة.

افتح المشروع المرفق مع المساعد وحدّد الحدث الذي ينبغي أن يرسل التأكيد التجريبي. استخدم صندوق المالك المضبوط فقط؛ ولا تسمح للزائر باختيار مستلمين عشوائيين.

ميّز قبول المزود للطلب عن وصول الرسالة إلى صندوق البريد.

مثال عملي

يرسل الإجراء المرفق رسالة ثابتة بعنوان Workshop confirmation إلى المستلم المُعدّ في الخادم. يقدم زائر النموذج اسمًا، لا وجهة إرسال يختارها بحرية. يساعد مرجع الرسالة المسترجع على تتبعها، لكنه لا يثبت وصولها.

افتح حزمة تدريب البريد الكاملة هذه. اتبع run-locally.txt واشرح قيم المرسل والمستلم ومفتاح المزود ورمز التدريب الخاصة. أبقِها خارج الملفات العامة. ساعدني في تشغيل المشروع وإرسال الاختبارات إلى صندوقي المضبوط فقط. افحص قبول المزود ووصول الرسالة الفعلي منفصلين، بما في ذلك محاولة مرفوضة.

Resend: إرسال البريد

ملفات هذه الخطوة

Start hereملفات ورشة العمل

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

أرسل بريدًا بعد إجراء في الموقع

تحوّل دالة خادم طلبًا مقبولًا إلى استدعاء مزوّد بريد.

ينبغي أن يطلب المتصفح إجراءً محددًا، لا أن يحتفظ ببيانات اعتماد بريدك ذات الامتيازات. في هذا المختبر، يرسل اسمًا إلى دالة خادم ترسل تأكيدًا نصيًا إلى صندوقك المعدّ.

Resend هو المسار المشروح. يستطيع مزوّد بريد معاملي آخر أداء الدور نفسه، لكن مصادقته والتحقق من المرسل وأحداث تسليمه تختلف. صندوق البريد البشري خدمة منفصلة.

مثال محلول

تعني استجابة «مقبول» أن المزوّد قبل طلب الإرسال. ولا تثبت تلقي صندوق بريد للرسالة. سنفحص ذلك الحد منفصلًا.

Resend: إرسال البريد

Extra implementation exercise

أعاد المزوّد معرّف رسالة، لكنك لم تفحص صندوق الوارد. ما الذي تستطيع ادعاءه بصدق؟

عرض حل نموذجي مشروح

قبل المزوّد طلبًا بذلك المرجع. يظل التسليم غير متحقق منه حتى تفحص أدلة التسليم وصندوق الاختبار.

  • تدعي القبول، لا تسليمًا مؤكدًا للوارد.
  • تحتفظ بمرجع الرسالة لفحص التسليم.

الخطوة 2

اضبط المشروع الجاهز وشغّله

دع المساعد يتولى توصيل أجزاء الخادم.

اتبع run-locally.txt مع مساعدك. أدخل القيم الخاصة بالحساب باستخدام server-env.example.txt، ثم شغّل المشروع الكامل وافتح عنوانه المحلي الفعلي.

أبقِ مفتاح المزود والمستلم الثابت على الخادم. رمز تدريب النموذج منفصل عن مفتاح المزود؛ ومعاينة الملف لا تشغّل خدمة البريد.

مثال عملي

تحدد قيم الخادم المرسل والمستلم والوصول إلى مزود البريد. يسمح رمز تدريبي منفصل بهذا الاختبار المخصص للمالك. لا ينفذ حقل متصفح مخفي أو معاينة ملف عادية ذلك الإعداد الخاص في الخادم.

Node.js: حالة دعم الإصدارات

ملفات هذه الخطوة

Start hereملفات ورشة العمل

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

اضبط مرسل تدريب مقيّدًا واحدًا

أبقِ بيانات اعتماد المرسل ومستلم الاختبار خارج المجلد العام.

قائمة محلية: أكد تثبيت Node وnpm، وثبّت أو تحقق من Netlify CLI، ثم اتبع run-locally.txt قبل إرسال النموذج. فتح الصفحة الثابتة أولًا مفيد للتخطيط لكنه لا يختبر دالة خادمها.

اقرأ netlify/functions/mini-mail.mjs. اضبط متغيرات بيئة البريد وLAB_TOKEN غير قابل للتخمين بطول 24 محرفًا على الأقل في مشروع استضافتك. يجب أن يكون MAIL_FROM مخولًا لدى المزوّد؛ وTEST_RECIPIENT صندوق اختبارك. لا تضع مفتاح API في public/app.js.

يُدخل المستخدم رمز وصول التدريب المنفصل لهذا المختبر المقيد؛ ولا يُضمّن في الصفحة أبدًا وليس مفتاح Resend الخاص بك. تتجاهل الدالة الوجهات التي يقدمها مقدم الطلب عمدًا. وتتحقق من حقل اسم صغير وتنشئ نصًا عاديًا. أضف حدود طلبات دائمة وراجع الحصص قبل إصدار عام؛ المختبر الخاص بالمالك ليس نظام ضبط إساءة استخدام كاملًا.

الوجهة تحت سيطرة الخادم عمدًا. يمكن لطلب متصفح مصطنع إضافة to='somewhere-else'، لكن الدالة تبني حمولة المزوّد بنفسها وتستخدم TEST_RECIPIENT. يمنع ذلك مقدم طلب المختبر من تحويل الميزة إلى مرسل لعناوين اعتباطية؛ ويظل الوصول العام محتاجًا إلى ضوابط إساءة استخدام دائمة.

للتسلسل المحلي الكامل، افتح run-locally.txt: جهز بيئة الجذر الخاصة، واربط مشروع التدريب فقط، وابدأ وكيل دوال Netlify. يسرد server-env.example.txt أسماء المتغيرات دون أسرار حقيقية. فتح HTML وحده لا يشغّل الخادم.

مثال محلول

لا يستطيع مهاجم يغيّر طلب متصفح إعادة توجيه بريد هذا المختبر لأن المستلم يأتي من بيئة الخادم. إخفاء عنوان في JavaScript لا يوفر تلك الحماية.

const {RESEND_API_KEY, MAIL_FROM, TEST_RECIPIENT} = process.env;
// Send only to TEST_RECIPIENT in this lab.

Node.js: حالة دعم الإصدارات

Extra implementation exercise

هل يحافظ نقل المفتاح إلى حقل مخفي على خصوصيته؟

عرض حل نموذجي مشروح

لا. تظل الحقول المخفية تُرسل إلى المتصفح. أبقِ بيانات الاعتماد في بيئة الخادم ونفّذ استدعاء المزوّد هناك.

  • تدرك أن القيم المرسلة للمتصفح قابلة للفحص.
  • تنقل الاستخدام ذي الامتيازات إلى بيئة الخادم.

الخطوة 3

أرسل اختبارًا واحدًا يسهل تمييزه

استخدم الواجهة واربط الأدلة بعضها ببعض.

أطلق التأكيد من الصفحة التي تعمل فعلًا. احفظ مرجع الاختبار وافحص الحدث المطابق لدى المزود ونسخة الرسالة في صندوق البريد.

إن فشل الطلب، فأبقِ الفشل ظاهرًا واحتفظ بسياق يكفي لإعادة المحاولة. لا تعالج خدمة غير متاحة باختلاق رسالة نجاح.

مثال عملي

عند استخدام الاسم الافتراضي Alex، يكون نص بريد البداية “Hello Alex. Your practice request was received.” قارن النسخة المستلمة فعليًا بالمحاولة المطابقة، لا برسالة قديمة.

ملفات هذه الخطوة

Start hereملفات ورشة العمل

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

اتبع الطلب والاستجابة المرفقين

يرسل الزر JSON؛ ويتحقق الخادم ثم يعيد حالة صادقة.

انشر المشروع المنفصل أو شغّله بأدوات الدوال المحلية للمضيف. فتح index.html كملف محلي لا يشغّل الخلفية. أرسل اسمًا مصطنعًا وافحص استجابة الشبكة.

يعيد الخادم 400 لمدخل مشوه و503 لإعداد مفقود و502 لاستدعاء مزوّد فاشل و202 عندما يقبل المزوّد الرسالة. يعالج المتصفح الفشل دون التظاهر بوصول البريد.

مثال محلول

تقول واجهة التدريب «Accepted by the mail provider. Check your test inbox.»، أي قبلها مزوّد البريد وافحص صندوق اختبارك. يطابق ذلك ما يعرفه الخادم في تلك اللحظة.

Extra implementation exercise

تعيد نقطة النهاية 503. هل تبدأ بتغيير لون الزر أم بفحص بيئة الخادم؟

عرض حل نموذجي مشروح

افحص متغيرات البيئة المعدّة وإعداد المرسل. لا يستطيع مظهر الواجهة توفير بيانات اعتماد خادم مفقودة.

  • تفحص إعداد الخادم المفقود أولًا.
  • لا تعتبر الطلب الفاشل بريدًا مكتملًا.

الخطوة 4

افحص سبب غياب الرسالة

ابحث عن حالة التسليم قبل تكرار الإرسال.

استخدم delivery-record.txt لمطابقة مرجع الاختبار مع حالة المزود والوجهة وفحص الوارد والبريد المزعج. اطلب من المساعد مساعدتك في المرحلة التي فشلت.

الرسالة المرتدة أو الوجهة المرفوضة تحتاج إلى فحص. تكرار الإرسال نفسه دون تشخيص قد يزيد الضوضاء دون إصلاح التسليم.

مثال عملي

القبول ثم الارتداد وعدم وجود رسالة في الصندوق يوجهان إلى فحص التسليم. ورفض رمز التدريب دون حدث لدى المزود يوجهان إلى إعداد الوصول. تقود هذه الملاحظات إلى خطوات تالية مختلفة.

ملفات هذه الخطوة

Start hereملفات ورشة العمل

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

تحقق من التسليم والفشل

اربط نقرة واحدة بمرجع مزوّدها والرسالة المستلمة الفعلية.

اعثر على الرسالة المقبولة في نشاط المزوّد وافحص حالة تسليمها. ثم افحص صندوق الاختبار المعدّ بما فيه الرسائل المزعجة. سجّل القبول وملاحظات النسخة المستلمة منفصلين.

جرّب اسمًا فارغًا عبر النموذج العادي وJSON مشوهًا عبر طلب مطوّر. في إعداد منفصل قابل للاستغناء عنه، تحقق من فشل نظيف عند فقد بيانات الاعتماد. لا تشارك أبدًا متون استجابات المزوّد التي قد تحتوي تفاصيل حساب.

مثال محلول

حدث تسليم ورسالة مستلمة مطابقة دليلان أقوى من زر أخضر. قبول مزوّد دون نسخة مستلمة يعني أن البحث في التسليم لم يُحسم.

Extra implementation exercise

يسرد المزوّد ارتدادًا لمرجع الاختبار. هل إعادة الإرسال نفسه فورًا أفضل خطوة تالية؟

عرض حل نموذجي مشروح

افحص الفشل المبلغ عنه وإعداد المستلم أولًا. أعد المحاولة بعد تحديد ما تغير فقط؛ تكرار إرسال مطابق لا يصلح وجهة غير صحيحة.

  • تفحص سبب الارتداد والوجهة.
  • تتجنب تكرار الطلبات دون تشخيص متغير.

الخطوة 5

أضف موضوعًا مفيدًا للرسالة

صف السلوك ودع المساعد ينفذه.

اطلب من المساعد إضافة موضوعين هما Project وQuestion بالقيمتين project وquestion. أدرج القيمة المختارة في نص التأكيد، مع إبقاء مستلم الخادم الثابت والمفتاح الخاص. اطلب مساعدته في اختبار القيمة غير المدعومة other دون إضافتها إلى الخيارات المسموحة.

أرسل اختبارًا مضبوطًا لكل خيار مسموح وافحص النص المستلم فعلًا. ينبغي رفض الموضوع غير المدعوم ورمز التدريب الخاطئ دون إرسال إلى المزود؛ اختبر هاتين المحاولتين السلبيتين بصورة منفصلة.

مثال عملي

للمهمة خياران مسموحان: Project وQuestion، ويُحفظان باسمَي project وquestion. يجب أن تصل القيمة المختارة إلى نص البريد. Other قيمة اختبار غير مدعومة عمدًا، وليست خيارًا ثالثًا مطلوبًا.

ملفات هذه الخطوة

Start hereملفات ورشة العمل

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

مهمتك: أضف تفصيل تأكيد ذا معنى

ضمّن موضوع طلب قصيرًا دون السماح بمستلمين اعتباطيين أو HTML.

أضف حقل موضوع بقيمتين مسموحتين. تحقق من قائمة السماح في الخادم وضمّن القيمة المختارة في التأكيد النصي. أبقِ المستلم ثابتًا في البيئة.

أرسل اختبارًا مطابقًا لكل قيمة وقيمة غير مدعومة واحدة. سجّل مرجع المزوّد ودليل التسليم الفعلي.

عدّل ملفات البداية أولًا. ثم قارن قائمة الموضوع وJSON الطلب وقائمة سماح الخادم سطرًا بسطر بالملفات المرجعية. مجلد المرجع بديل كامل لفحص عملك، وليس مجلدًا إضافيًا تلصقه عشوائيًا داخل public/.

مثال محلول

قبول «project» و«question» فقط أوضح للمراجعة من نسخ محتوى مقدم طلب اعتباطي إلى كل حقل بريد.

يتوفر الشرح المرجعي الكامل في reference/assignment-walkthrough.txt. قارن خطواته بنتيجتك؛ واملأ سجل الاختبار بملاحظات من مشروعك أنت.

Extra implementation exercise

وسّع التأكيد بموضوع متحقق منه وأظهر طلبات ناجحة وأخرى مرفوضة.

عرض حل نموذجي مشروح

تستخدم توسعة الموضوع قيمتين مسموحتين بالضبط، «project» و«question». أضف الاختيار إلى النموذج وضمّن topic في JSON وتحقق من قائمة السماح في الخادم قبل استدعاء مزوّد البريد. تعرض الواجهة والدالة المرجعيتان التغييرات الكاملة.

أبقِ TEST_RECIPIENT تحت سيطرة الخادم حتى إن قدم طلب مصطنع عنوانًا آخر. قد يصل موضوع مسموح ورمز تدريب صالح إلى قبول المزوّد؛ ويجب أن يعيد موضوع غير مدعوم 400 دون استدعائه. القبول ليس استلام صندوق وارد.

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

  • يرفض الخادم المواضيع غير المدعومة ويحتفظ بالمستلم الثابت.
  • يظهر الموضوعان المسموحان في رسائل مستلمة مطابقة.

هل أفادك هذا الدرس؟

اترك إعجابًا، أو شاركه مع شخص قد يستفيد منه.

واصل التعلّم

استكشف الدروس الأخرى