كيف ينفّذ فريق المنتج Postmark API بأمان؟

حدّد حدود التطبيق قبل Postmark

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

استخدم رموز الخادم بنطاق تشغيلي ضيق

توثّق واجهة البريد في Postmark الترويسة X-Postmark-Server-Token للوصول إلى API على مستوى الخادم. خزّن كل رمز في خدمة أسرار مُدارة ولا تكشفه إلا للعامل الذي يحتاج ذلك الخادم وتلك البيئة. لا تضع الرموز أبدًا في شيفرة العميل أو مستودع المصدر أو عناوين URL أو السجلات أو التحليلات أو القوالب أو لقطات الشاشة أو التذاكر أو المطالبات (prompts) أو عينات الاختبار. افصل الإنتاج عن التطوير وعن المنتجات غير المرتبطة بحيث يكون أثر الإبطال أو إساءة الاستخدام محدودًا. تدرّب على التدوير بتجهيز رمز بديل عبر الإدارة المعتمدة، وتحديث العامل، وإرسال رسائل مضبوطة، وتأكيد أدلة API والأحداث، ثم إبطال الرمز القديم. وتعامل مع أخطاء المصادقة غير المتوقعة بوصفها شرط إيقاف مؤقت لا دعوة لإعادة تجربة بيانات الاعتماد بسرعة. وقيّد إدارة لوحة التحكم بمصادقة قوية وأدوار. يفوّض رمز الخادم عمليات Postmark API لخادمه؛ ولا يزال على التطبيق تفويض المستأجر والمُرسِل والمستلِم والقالب وفئة الرسالة.

وثّق هوية المُرسِل بدقة

استخدم توقيع مُرسِل أو نطاقًا موثَّقًا تتحكم فيه المؤسسة، وتأكد من عنوان From الدقيق المستخدم في كل تدفق. احصر نطاق From الظاهر ومسار SMTP للارتداد (return path) ونطاق DKIM d= والمحدِّد (selector) وعنوان الرد وتدفق الرسائل المرسِل على عينات خام مستلَمة. وانشر سجلات DNS التي تتطلبها Postmark حاليًا للإعداد المختار فقط، بعد مراجعة ملكية SPF وDKIM وDMARC القائمة. احتفظ بالقيم السابقة وتعليمات التراجع. توثيق المزوّد دليل على أن فحص الإعداد لديه نجح؛ لكنه لا يثبت أن كل مسار في التطبيق يستخدم تلك الهوية، ولا أن DMARC محاذية، ولا أن المستلِمين وافقوا، ولا أن الرسائل تصل إلى صناديق الوارد. أبقِ تفويض المُرسِل الخاص بكل مستأجر في التطبيق، وامنع قيم From العابرة للمستأجرين. اختبر النطاقات الفرعية والردود والارتدادات والبيئات الدنيا ومسارات القوالب. ولا تُضعف سياسة SPF أو DMARC للمؤسسة لمجرد جعل مؤشر في لوحة التحكم أخضر.

ابنِ طلب POST واحدًا صريحًا للبريد

توثّق Postmark المسار POST /email بحقول JSON للمُرسِل والمستلِمين والموضوع ومتن النص أو HTML وReplyTo والترويسات والوسوم أو البيانات الوصفية وتدفق الرسائل والمرفقات وخيارات التتبع. اكشف الحقول التي يحتاجها المنتج فقط. تحقق من العناوين ووحّدها، وحدّد أعداد المستلِمين والمرفقات، وارفض حقن الترويسات، وهرّب (escape) قيم القالب بحسب سياق المخرجات، وولّد النص وHTML من مراجعة معتمدة واحدة. ولا تضع أسرارًا أو بيانات شخصية غير ضرورية في الوسوم أو البيانات الوصفية أو الترويسات أو المواضيع أو أسماء المرفقات لأنها قد تظهر في نشاط المزوّد وأحداثه. اختر MessageStream من إعدادات موثوقة، لا من مدخلات الطلب التعسفية. وأبقِ حمولة المزوّد في محوّل واحد حتى لا تعتمد شيفرة العمل على كل حقول Postmark. خزّن مراجعة المحتوى أو تجزئة آمنة للخصوصية عندما تبررها احتياجات التدقيق بدلًا من تسجيل متن الرسالة كاملًا.

فسّر الاستجابة الفورية بتحفظ

توثّق نقطة نهاية الرسالة الواحدة في Postmark حقول الاستجابة ومنها ErrorCode وMessage وMessageID وSubmittedAt ومعلومات المستلِم. احفظ حالة HTTP الدقيقة واستجابة المزوّد المنظَّمة مع محاولة التطبيق. تُظهر الاستجابة الناجحة وMessageID أن Postmark قبلت طلب API بحسب دلالاتها الموثَّقة؛ لكنهما لا تُظهران أن الخادم الوجهة قبل الرسالة ولا أنها وصلت إلى صندوق الوارد. صنّف أخطاء التحقق وتوقيع المُرسِل والمصادقة والحمولة المشوّهة والحصة والسياسة قبل إعادة المحاولة. وانتهاء مهلة الطلب ملتبس لأن Postmark ربما قبلت العملية بينما فات العميل استلام الاستجابة. أبقِ تلك المحاولة غير معروفة، وابحث في نشاط المزوّد أو الأحداث اللاحقة بواسطة بيانات ارتباط آمنة، وطبّق قاعدة مطابقة خاصة بفئة الرسالة قبل إعادة الإرسال. ولا تعِد أبدًا بتسليم مرة واحدة تمامًا (exactly-once) ولا تنشئ حدثًا منطقيًا جديدًا لمجرد أن طلب HTTP واحدًا أخفق.

صمّم إعادة المحاولات وفق أدلة المزوّد والنقل

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

أمّن webhooks التسليم والارتداد

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

نمذج حالات التسليم والارتداد والمنع

حوّل أدلة التسليم والارتداد من Postmark إلى نموذج داخلي على مستوى المستلِم مع الاحتفاظ بنوع المزوّد الأصلي وMessageID والطابع الزمني وحالة الارتداد أو تصنيفه والتشخيص. قبول API ومعالجة Postmark وقبول الخادم الوجهة وعدم التسليم اللاحق وموضع المجلد في صندوق البريد والتفاعل كلها حالات مختلفة. ويعكس حدث «تم التسليم» عادةً ملاحظة المزوّد الموثَّقة لدى الخادم الوجهة، لا رؤية للمجلد النهائي. وقد تبرر الإخفاقات المؤقتة معالجة نقل محدودة؛ أما إخفاقات العنوان الدائمة المؤكَّدة فينبغي أن تنشئ منعًا مقيَّدًا بالمستلِم. ويجب أن تحدّث الشكاوى وإلغاءات الاشتراك سلامة المستلِم قبل أي مهام لاحقة. واحمِ إعادة التفعيل اليدوية بالتفويض والسبب وسجل التدقيق. وأبقِ حالة الموافقة والمنع التي يملكها المنتج حتى لا يؤدي الترحيل إلى ضياع حماية المستلِم. ولا تستنتج قراءة الإنسان من تتبع الفتح أو النقر، فهو أداة قياس تفاعل يمكن أن تتأثر بتقنيات الخصوصية.

اختبر بيئة sandbox والإنتاج ومسارات الإخفاق

استخدم مرافق الاختبار أو sandbox الموثَّقة في Postmark ومستلِمين مخصصين خاضعين للتحكم، لا عناوين عملاء حقيقيين، لإحداث إخفاقات حتمية. اختبر الرموز الصالحة وغير الصالحة وهويات From غير المصرح بها والمستلِمين المعتمدين والمحظورين والنص وHTML وUnicode والمرفقات وتقليل البيانات الوصفية وتدفقات الرسائل وانتهاء مهلة الطلب قبل القبول وبعده واستجابة حد المعدل ومصادقة webhook والتسليم المكرر والأحداث غير المرتبة وتصنيفات الارتداد والمنع وتدوير الرموز. تحقق من الترويسات الخام المستلَمة ومحاذاة DKIM وDMARC وReply-To وإعدادات التتبع وارتباط MessageID. وتأكد من أن البيئات الدنيا لا تصل إلى مستلِمي الإنتاج. وأجرِ اختبارات تصدير وترحيل لقوائم المنع والأدلة التشغيلية. وأوقف الإطلاق عند وجود وصول عابر للمستأجرين إلى المُرسِل أو الأحداث، أو تعذّر فرض المنع، أو قبول webhook ملتبس، أو أسرار في السجلات، أو إعادة محاولات غير محدودة، أو العجز عن إيقاف الخادم أو التدفق المتأثر مؤقتًا بأمان.

كيف ينسجم SendHQ

SendHQ هو واجهة API للبريد الإلكتروني على مستوى مساحة العمل لاتصال المنتج المتوقع. تغطي وثائقه العامة إرسال النطاقات الموثقة والبريد الوارد والقوالب المستضافة وأحداث التسليم وقوائم المنع ولوحة تحكم على الويب.

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

المصادر

• Postmark Email API — Postmark
• نظرة عامة على Postmark API — Postmark
• نظرة عامة على Postmark Webhooks — Postmark
• Postmark Bounce webhook — Postmark
• RFC 5321: بروتوكول نقل البريد البسيط (SMTP) — محرّر RFC