كيف ينفّذ فريق المنتج واجهة Resend API للبريد الإلكتروني بأمان؟

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

ابدأ بعملية ضيقة في التطبيق مثل توثيق الحساب أو إيصال أو تنبيه أمني أو إشعار طلبه المستلِم. وينبغي أن تخوّل نقطة نهاية المنتج العامة المستدعي والمستأجر وفئة الرسالة وهوية المُرسِل والمستلِمين والقالب قبل أن توجد أي حمولة لـ Resend. ولا تدع المتصفح يقدّم `from` أو `to` أو HTML أو خيارات مزوّد عشوائية وهو يحمل بيانات اعتماد قابلة لإعادة الاستخدام. أنشئ سجلًا داخليًا دائمًا للإرسال يتضمن مفتاح حدث التطبيق والمستأجر ونسخة القالب والمُرسِل المعتمد ومجموعة المستلِمين والحالة الحالية. ويستطيع عامل تحويل هذا السجل إلى طلب المزوّد. يُبقي هذا الحد مفاتيح API ومحتوى الرسائل غير الموثوق بعيدًا عن العملاء، ويجعل منع التكرار قابلًا للاختبار، ويتيح للمنتج تغيير المزوّدين دون إعادة كتابة كل سير عمل. وافصل في النموذج الداخلي بين الرسائل المعاملاتية والرسائل المعتمدة على الموافقة كي تبقى التفضيلات وعمليات المنع وقرارات الحوادث صريحة.

وثّق النطاق المستخدم بدقة في عنوان From

أضف نطاقًا تملكه في Resend وانشر سجلات DNS المعروضة لذلك النطاق. وثّق النطاق التنظيمي أو الفرعي الفعلي المستخدم في عنوان From الظاهر بدلًا من افتراض أن هوية أب لا صلة لها به تغطيه. راجع سياسة SPF وDMARC القائمة قبل تغيير DNS، ولا تنشئ أبدًا سجل SPF ثانيًا لاسم المضيف نفسه. استخدم نطاقًا فرعيًا مخصصًا للإرسال عندما تبرر متطلبات العزل أو الملكية أو الترحيل ذلك. وبعد أن تبلّغ لوحة التحكم بالتوثيق، افحص رسالة اختبار مستلَمة لتأكيد عنوان From الظاهر وهوية توقيع DKIM ومسار العودة ونتائج المصادقة وسلوك الرد. توثيق المزوّد يثبت أن هوية مهيأة اجتازت فحص الإعداد لديه. لكنه لا يثبت موافقة المستلِم ولا قبول الخادم المستقبِل ولا الوصول إلى صندوق الوارد ولا حسن السمعة. احتفظ بملكية DNS وسجل التغييرات خارج لوحة تحكم المزوّد ليبقى التدوير والتراجع ممكنين.

أنشئ مفتاح API بأقل الصلاحيات لكل حِمل

توثّق Resend مفاتيح API بمستويات وصول وتقييد اختياري بنطاق. وينبغي أن يستخدم عامل الإرسال مفتاحًا مقيّدًا بصلاحية الإرسال، وعندما تسمح البنية، بالنطاق الوحيد الذي يملكه ذلك الحِمل. وأبقِ الإدارة والنطاقات وwebhooks وإدارة الحساب تحت سلطة منفصلة. أنشئ مفاتيح منفصلة للتطوير والاختبار المرحلي والإنتاج حتى لا تستطيع بيئة أدنى الإرسال بهوية الإنتاج أو استهلاك حدودها. خزّن كل سر مباشرة في مخزن أسرار مُدار، واكشفه فقط لعملية الخادم التي تحتاجه، ومرّره كتخويل Bearer عبر HTTPS. ولا تنسخ المفتاح إلى التحكم في المصدر أو ناتج البناء أو السجلات أو القوالب أو التحليلات أو التذاكر أو المطالبات (prompts). وينبغي التدرّب على التدوير: أنشئ بديلًا بالنطاق ذاته، وحدّث العامل، وتحقق من الحركة الخاضعة للتحكم وربط الأحداث، ثم ألغِ المفتاح القديم. ونبّه عند إخفاقات مصادقة وتخويل غير متوقعة لأنها قد تشير إلى انتهاء الصلاحية أو الإلغاء أو انحراف النطاق أو انكشاف السر.

اجعل هناك مهمة دائمة واحدة ومحاولة إرسال غير مكرَّرة واحدة

احجز مهمة الإرسال الداخلية قبل استدعاء Resend. اشتقّ قيمة عدم التكرار من حقيقة ثابتة في المنتج مثل المستأجر ونوع العملية ومعرّف حدث التطبيق غير القابل للتغيير، لا من محاولة إعادة عشوائية. وأرسل هذه القيمة في الترويسة `Idempotency-Key`. وتوثّق Resend حاليًا أن هذه المفاتيح تمنع طلبات البريد المكرَّرة وتنتهي صلاحيتها بعد 24 ساعة ويمكن أن تحتوي على 256 حرفًا كحد أقصى. وهذه النافذة لدى المزوّد مفيدة لكنها ليست ضمانًا كاملًا لمنع التكرار على مستوى المنتج. أبقِ قيد تفرّد على مفتاح الحدث الداخلي لسير العمل الأطول، وسلسل العمال الذين قد يستحوذون على المهمة نفسها، واحفظ معرّف رسالة المزوّد الذي يعيده الطلب الناجح. وإذا جعلت مهلة الشبكة القبول ملتبسًا، فأبقِ المهمة في حالة مجهولة وطابقها مع سجلات المزوّد أو أحداثه قبل إعادة الإرسال. وإعادة استخدام مفتاح واحد ثابت للعملية المنطقية نفسها أكثر أمانًا من توليد مفتاح جديد لكل إعادة محاولة نقل.

ابنِ طلب البريد وتحقق منه عن قصد

تقبل نقطة نهاية إرسال البريد في Resend عنوان From والمستلِمين والموضوع ومحتوى الرسالة، مع خيارات موثّقة مثل النص وHTML والمحتوى المعروض بـ React والقوالب وCc وBcc وreply-to والترويسات والمرفقات والوسوم والتسليم المجدول. اكشف الجزء الفرعي الذي يحتاجه المنتج فقط. تحقق من صياغة العنوان وملكية المستأجر، وضع سقفًا لعدد المستلِمين والمرفقات دون حدود المزوّد، وارفض حقن الأسطر الجديدة في الترويسات، وابنِ المحتوى المتعلق بـ MIME عبر مكتبات مُصانة أو حقول موثوقة من المزوّد. ولا تضع بيانات اعتماد أو بيانات شخصية حساسة أو مدخلات عملاء غير مقيّدة في الوسوم أو الترويسات. خزّن نسخة القالب والمتغيرات المنقّحة بدلًا من تسجيل المحتوى الكامل. وينبغي أن يعيد المحوّل الداخلي نتيجة ضيقة مثل معرّف المزوّد المقبول أو إخفاق مصنَّف، لا أن يسرّب تفاصيل استجابة المزوّد إلى شيفرة الأعمال. يتيح هذا تحديث أسماء الحقول الخاصة بالمزوّد أو إصدارات SDK أو حدود الطلب دون تغيير عقد أحداث المنتج.

صنّف استجابات API وحدود الاستخدام قبل إعادة المحاولة

تعامل مع استجابة HTTP بوصفها ملاحظة واحدة في سير العمل. تعيد استجابة الإرسال الناجحة معرّف رسالة ينبغي حفظه مع المهمة الداخلية، لكنها لا تثبت قبول الوجهة ولا الوصول إلى صندوق الوارد. صحّح أخطاء التحقق والمصادقة والنطاق والأذونات والحمولة بدلًا من إعادة محاولتها دون تمييز. وتوثّق Resend حدود طلبات API وتعيد ترويسات حد المعدّل والحصة، بما فيها حقول تصف السعة المتبقية وموعد إعادة الضبط ومهلة إعادة المحاولة؛ وينبغي أن تنتظر استجابة 429 الفترة الموثّقة مع إضافة عشوائية (jitter). أعد محاولة إخفاقات النقل وأخطاء الخادم المؤهلة بتراجع أُسّي وعدد محدود من المحاولات ومفتاح عدم التكرار المنطقي نفسه ما دامت نافذته الموثّقة سارية. وتتطلب الإخفاقات الملتبسة مطابقة لأن المزوّد ربما قبل الرسالة حتى لو لم يتلقَّ العميل الاستجابة. نبّه عندما تتجمع الإخفاقات المتكررة بحسب النطاق أو القالب أو المفتاح أو المستأجر، لكن أبقِ بيانات الاعتماد والمحتوى الكامل وبيانات المستلِمين غير الضرورية خارج سجلات التشغيل.

صادق على طلبات webhook قبل معالجة الأحداث

اضبط نقطة نهاية webhook مخصصة عبر HTTPS واحتفظ بجسم الطلب الخام كما هو بدقة. توثّق Resend توقيع webhook عبر ترويسات متوافقة مع Svix وأسرار توقيع. تحقق من معرّف webhook والطابع الزمني والتوقيع على الحمولة غير المعدَّلة قبل تحليل JSON أو إعادة تسلسله، واستخدم تدفق التحقق الرسمي أو مكتبة متوافقة مُصانة. ارفض الطلبات غير الصالحة أو القديمة، وضع سقفًا لحجم الطلب، وأبقِ سر التوقيع منفصلًا عن مفتاح الإرسال. وبعد المصادقة، احفظ الحدث أو ضعه في الطابور بشكل دائم قبل الإقرار به حتى لا يتخلص انهيار العملية بصمت من أدلة التسليم. قد تعيد أنظمة التسليم محاولة webhooks وتكررها، فاستخدم معرّف الحدث مفتاحًا لإزالة التكرار واجعل انتقالات الحالة أحادية الاتجاه. ولا يجوز لحدث متأخر أو مكرَّر أن يكتب فوق نتيجة نهائية أكثر إفادة لمجرد أنه وصل أخيرًا. سجّل إخفاقات التحقق وتأخر الأحداث كإشارات تشغيلية دون حفظ محتوى الرسالة الخام بعد مدة الاحتفاظ الضرورية.

نمذج أحداث المزوّد دون المبالغة في وصف التسليم

تنشر Resend أنواع أحداث بريد مسماة تشمل sent وdelivered وdelivery delayed وbounced وcomplained وfailed وopened وclicked. اربط أسماء المزوّد هذه بنموذج حالات داخلي مع نوع الحدث الأصلي ومعرّف رسالة المزوّد ومعرّف الحدث والطابع الزمني ونطاق المستلِم وبيانات التشخيص المتاحة. يصف حدث sent تقدّم المزوّد. ويبلّغ حدث delivered عن التسليم وفق دلالات أحداث Resend الموثّقة، لكن نجاح SMTP لدى نظام مستقبِل لا يكشف المجلد النهائي للمستلِم. أما الفتح والنقر فهما ملاحظتا تفاعل لا دليل تسليم، وقد تؤثر فيهما تقنيات الخصوصية. وينبغي أن تحدّث الارتدادات والشكاوى والإخفاقات الدائمة حالة سلامة المستلِم قبل قرار الإرسال التالي. أبقِ سجل أحداث المزوّد للإضافة فقط واشتق الحالة المعروضة للمستخدم من قواعد صريحة. وهذا يحفظ الأدلة للدعم ويتجنّب إعادات المحاولة غير الآمنة بعد انتقال المسؤولية أو بعد أن قدّم المستلِم إشارة سلبية.

اختبر مسارات الإخفاق والتعافي بمستلِمين خاضعين للتحكم

استخدم مفتاحًا غير إنتاجي ونطاقًا فرعيًا موثَّقًا خاضعًا للتحكم وصناديق بريد يملكها الفريق. اختبر محتوى النص وHTML وسلوك reply-to وحدود المرفقات ومفاتيح عدم التكرار الثابتة ومعرّفات المزوّد المخزَّنة. قدّم المهمة المنطقية نفسها مرتين وتأكد من أن ضوابط التطبيق والمزوّد لا تنشئ تكرارًا غير مقصود. وجرّب الحمولة غير الصالحة والنطاق الخاطئ والمفتاح الملغى والصلاحية غير الكافية وحد المعدّل ومهلة النقل والارتداد والشكوى وتأخر التسليم وwebhook المكرَّر وجسم التوقيع المعدَّل والطابع الزمني القديم لـ webhook وتدوير سر التوقيع. وتأكد من أن استقبال الأحداث دائم قبل الإقرار به وأن سلامة المستلِم تحجب مهمة لاحقة. واختبر تدوير DNS وإزالة المزوّد دون حذف سجلات لا علاقة لها. وينبغي أن تغطي لوحات المراقبة إخفاقات الإرسال وزمن الاستجابة وإخفاقات التحقق من webhook وتأخر الأحداث والارتدادات والشكاوى وطوابير المطابقة. وراجع وثائق Resend الحالية وإعدادات الحساب عند الإطلاق لأن الحصص والحدود وحقول الأحداث والأذونات المتاحة قد تتغير باستقلال عن شيفرة التطبيق المنشورة.

قارن قدرات API المنشورة قبل الترحيل

ينشر SendHQ عقد OpenAPI 3.1 لواجهة API للبريد الإلكتروني على مستوى مساحة العمل، يشمل إرسال النطاقات الموثقة والبريد الوارد والقوالب المستضافة وأحداث التسليم وقوائم المنع. قبل ترحيل تكامل، قارن أجسام الطلبات والمصادقة وعدم التكرار والمعرّفات المعادة وأشكال الأخطاء وwebhooks وقواعد النطاق وسلوك المنع، ثم تحقق منها باختبارات على مستوى الحقول. لا تفترض التوافق من أسماء نقاط نهاية متشابهة.

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

المصادر

• Resend Send Email API — Resend
• مفاتيح Resend API — Resend
• نطاقات Resend — Resend
• مفاتيح عدم التكرار في Resend — Resend
• حدود الاستخدام في Resend — Resend
• webhooks في Resend — Resend
• التحقق من طلبات webhook في Resend — Resend
• أنواع أحداث webhook في Resend — Resend
• RFC 5321: بروتوكول نقل البريد البسيط (SMTP) — محرّر RFC
• عقد OpenAPI الخاص بـ SendHQ — SendHQ