دليل · SendGrid API

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

نفّذ SendGrid API خلف خدمة بريد على الخادم، باستخدام نطاق إرسال موثَّق ومفتاح API مقيَّد بصلاحية Mail Send. تحقق من كل رسالة قبل استدعاء `POST /v3/mail/send`، واحفظ سجل الإرسال الخاص بك، والتقط `X-Message-ID` من الاستجابة. عالج حمولات Event Webhook الموقَّعة انطلاقًا من بايتاتها الخام، وأزل تكرار الأحداث، والتزم بالارتدادات وبلاغات البريد المزعج وإلغاءات الاشتراك. وتعامل مع `202 Accepted` وتسليم الخادم المستقبِل والوصول إلى صندوق الوارد بوصفها حالات منفصلة، مع إعادة محاولات محدودة للإخفاقات المؤقتة فقط.

حدّد مهمة إرسال ضيقة ومشروعة

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

وثّق نطاق إرسال مخصصًا

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

أصدر مفاتيح API بأقل صلاحية لكل بيئة

أنشئ مفتاح API من نوع Custom Access بالصلاحيات التي يحتاجها عبء العمل فقط، وهي عادةً صلاحية Mail Send لعامل الإرسال. لا تمنح مُرسِلًا روتينيًا Full Access إلى القوالب أو قوائم المنع أو أعضاء الفريق أو الإحصاءات أو إعداد IP أو إدارة الحساب. استخدم مفاتيح منفصلة للتطوير والاختبار المرحلي والإنتاج، بأسماء تحدد الخدمة المالكة وغرض التدوير. يعرض SendGrid المفتاح الجديد مرة واحدة، لذا ضعه مباشرةً في مدير أسرار البيئة ولا تنسخه أبدًا إلى مستودع المصدر أو مستند مشترك. وأثناء التشغيل اقرأه من إعدادات مدعومة بالأسرار ومرّره فقط في الترويسة `Authorization: Bearer` عبر HTTPS. واختبر تدوير المفتاح بوصفه تسلسلًا تشغيليًا: أنشئ مفتاحًا بديلًا بالصلاحيات الضيقة المكافئة، وانشره، وتحقق من نجاح حركة مضبوطة، ثم أبطل المفتاح القديم. ونبّه عند استجابات 401 أو 403 غير المتوقعة لأنها قد تدل على مفتاح مفقود أو بيانات اعتماد مُبطَلة أو عدم تطابق الصلاحيات أو تغيير غير آمن في الإعداد.

ابنِ كل طلب Mail Send وسجّله

أنشئ سجلًّا صادرًا داخليًا واحدًا قبل الاتصال بـ SendGrid. امنحه مفتاح حدث ثابتًا للتطبيق والمستأجر وهوية المُرسِل والمستلِمين المعتمدين وفئة الرسالة ونسخة القالب والحالة. وابنِ حمولة المزوّد من ذلك السجل باستخدام `personalizations` و`from` و`subject` وجزء محتوى مدعوم واحد على الأقل أو قالب ديناميكي معتمد. تحقق من صياغة العناوين وعدد المستلِمين وحجم المرفق وبيانات القالب والترويسات المخصصة قبل الاتصال بالشبكة. تحدّد النظرة العامة الحالية لـ Mail Send في SendGrid الحجم الكلي للطلب بما فيه المرفقات بأقل من 30 MB، وإجمالي المستلِمين عبر To وCc وBcc بما لا يزيد على 1,000. والطلبات الأصغر والمخصصة لغرض محدد أسهل في التدقيق والاسترداد. وعند استجابة `202 Accepted` التقط الترويسة `X-Message-ID` وأرفقها بالسجل الصادر. ولا تضع بيانات شخصية في الفئات أو الوسائط الفريدة؛ إذ يحذّر SendGrid من أن هذه القيم قد تُحفظ وتُعرض خارج الحمايات المتوقعة لمحتوى الرسالة.

تحقق من Event Webhook وعالجه

اضبط Event Webhook في SendGrid على نقطة نهاية HTTPS قادرة على الاحتفاظ بمتن الطلب الخام. فعّل التوقيع التشفيري أو OAuth 2.0 أو كليهما. وللتسليم الموقَّع، تحقق من الطابع الزمني و`X-Twilio-Email-Event-Webhook-Signature` مقابل البايتات الخام الدقيقة قبل تحليل JSON؛ إذ تحذّر Twilio من أن إعادة تسلسل الحمولة قد تغيّر البايتات وتُبطل التحقق. ارفض المدخلات غير الموثَّقة، وطبّق حدًّا معقولًا لحجم الطلب، وامنع إعادة الإرسال وفق سياسة الطابع الزمني التي يختارها الفريق. وبعد التحقق، ضع دفعة الأحداث في الطابور أو خزّنها بشكل دائم قبل إرجاع النجاح. وأزل التكرار عبر `sg_event_id`، ثم اربط `sg_message_id` و`X-Message-ID` المخزَّن وقيمة ارتباط داخلية غير حساسة. واجعل انتقالات الحالة أحادية الاتجاه حتى لا يستطيع حدث processed متأخر أن يستبدل نتيجة delivered أو bounce لاحقة. واحتفظ بحدث المزوّد الأصلي في تخزين مقيَّد لاستكشاف الأخطاء، وقلّل الاحتفاظ بالعناوين ونص الاستجابة وبيانات التفاعل إلى ما يحتاجه المنتج والسياسة فعلًا.

نمذج القبول والتسليم والوصول إلى صندوق الوارد بدقة

تعني استجابة HTTP `202 Accepted` في SendGrid أن الطلب قُبل ووُضع في الطابور للمعالجة. ولا تعني أن الوجهة قبلت الرسالة. أما حدث webhook من نوع `processed` فيعني أن SendGrid قبلت الرسالة وتستطيع محاولة تسليمها. وحدث `delivered` يعني أن SendGrid تبلّغ بأن خادم البريد المستقبِل قبلها، غالبًا مع استجابة SMTP. ومع ذلك لا يثبت هذا الوصول إلى صندوق الوارد، لأن النظام المستقبِل قد يصنّف البريد المقبول في علامة تبويب في صندوق الوارد أو الحجر أو مجلد البريد غير الهام أو موضع آخر. أبقِ هذه الحالات منفصلة في التخزين وواجهات المستخدم: مطلوب، ومقبول لدى المزوّد، ومعالَج، ومؤجَّل، ومقبول لدى الخادم المستقبِل، ومرتد، ومُسقَط، ومشتكى منه، وممنوع. وتجنّب ترجمة كل استجابة HTTP غير خطأ إلى «سُلِّمت». كما أن إشارات التفاعل مثل الفتحات ليست دليل تسليم ويمكن أن تتأثر بميزات الخصوصية. وتجعل أسماء الحالات الدقيقة تحقيقات الدعم وإعادة المحاولات وقرارات قابلية التسليم أكثر أمانًا.

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

تعامل مع أخطاء المزوّد بحسب الفئة بدلًا من إعادة محاولة كل استجابة غير 202. تتطلب 400 عادةً تصحيح الحمولة أو المُرسِل أو بيانات القالب أو الترويسات المحجوزة. وتشير 401 إلى المصادقة؛ وقد تدل 403 على نقص الصلاحية أو سياسة الحساب؛ وتتطلب 413 تقليل حجم الرسالة. يوثّق SendGrid ترويسات حد المعدل لكل نقطة نهاية ويعيد 429 عند استنفاد الحصة في فترة التجديد، لذا أخّر حتى وقت إعادة الضبط وأضف تشويشًا عشوائيًا (jitter) بدلًا من إنشاء إعادات محاولة متزامنة. وأعد محاولة 5xx وإخفاقات النقل بتراجع أُسّي وعدد محاولات محدود وتنبيه تشغيلي. وتحتاج مهلات الانتهاء الملتبسة إلى عناية خاصة: فقد يكون المزوّد قبل الطلب رغم أن العميل فاتته الاستجابة. أبقِ السجل الصادر في حالة غير معروفة، وابحث عن أحداث مرتبطة، واشترط قاعدة مطابقة متعمدة قبل إعادة الإرسال. ولا تُلغي واجهات المزوّد الحاجة إلى منع التكرار على مستوى المنتج. ولا تعِد أبدًا محاولة ارتداد دائم معروف أو مستلِم غير صالح أو إلغاء اشتراك أو وجهة بلاغ بريد مزعج بوصفه خطأ بنية تحتية مؤقتًا.

احترم قوائم المنع واختيارات المستلِمين

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

اختبر دورة الحياة كاملة قبل حركة الإنتاج

ابدأ بمفتاح SendGrid غير إنتاجي ونطاق فرعي موثَّق مضبوط. تحقق من DNS، ثم أرسل نسخ النص العادي وHTML إلى صناديق وارد يملكها الفريق. أكّد استجابة `202` و`X-Message-ID`، وتحقق من أن أحداث webhook الموقَّعة ترتبط بالسجل الصادر المحلي. جرّب مسارات الحمولة غير الصالحة والمفتاح المُبطَل والصلاحية المفقودة والمرفق الكبير جدًا وحد المعدل والتأجيل والارتداد والإسقاط والحدث المكرر دون استخدام عناوين عملاء حقيقيين. وتأكد من أن التحقق من webhook يرفض متنًا معدَّلًا وأن المعالج لا يقرّ إلا بعد الالتقاط الدائم. واختبر تدوير المفاتيح والتراجع عن القالب وفرض المنع ومهلة عميل ملتبسة. وأضف لوحات لإخفاقات الطلبات وتأخر الأحداث والتأجيلات والارتدادات وبلاغات البريد المزعج وإخفاقات توقيع webhook، بمعرّفات للمستأجر والرسالة دون بيانات اعتماد أو محتوى كامل. وأخيرًا، راجع وثائق SendGrid وحدود الحساب الحالية عند الإطلاق لأن استحقاقات الباقة والميزات الإقليمية والحصص وسياسات المزوّد قد تتغير باستقلال عن شيفرة التطبيق.

قارن التبعيات الخاصة بالمزوّد

يكون التكامل المباشر مع SendGrid مناسبًا عندما يعتمد فريق عمدًا على حقول طلبات SendGrid الخاصة وقوالبه وضوابط حسابه وتنسيقات webhook وقوائم المنع والملكية التشغيلية. تصف وثائق SendHQ العامة واجهة API للبريد الإلكتروني على مستوى مساحة العمل مع إرسال نطاقات موثقة وبريد وارد وقوالب مستضافة وأحداث تسليم وقوائم منع ولوحة تحكم على الويب. قبل الترحيل، راجع حمولات المزوّدين وأحداثهما وضوابط الهوية وقوائم المنع والمتطلبات الإقليمية ومعرّفات المزوّد المخزنة.

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

هل يعني رد SendGrid 202 Accepted أن البريد سُلِّم؟

لا. فهو يعني أن SendGrid قبلت طلب API للمعالجة. استخدم أحداث التسليم في Event Webhook لمعرفة ما إذا كان الخادم المستقبِل قبل الرسالة، وأبقِ الوصول إلى صندوق الوارد نتيجة منفصلة لا تثبتها استجابة API.

ما الصلاحية التي ينبغي أن يملكها مفتاح الإرسال في SendGrid؟

استخدم مفتاح Custom Access مقيَّدًا بإمكانية Mail Send التي يحتاجها العامل. تجنّب Full Access للإرسال الروتيني، واستخدم مفاتيح منفصلة مُدارة بالأسرار للتطوير والاختبار المرحلي والإنتاج والإدارة وأي عبء عمل آخر بصلاحيات مختلفة جوهريًا.

كيف يُتحقق من توقيع SendGrid Event Webhook؟

احتفظ بمتن HTTP الخام كما هو، واقرأ ترويستي توقيع Twilio والطابع الزمني، وتحقق منهما قبل تحليل JSON أو إعادة تسلسله. طبّق الحماية من إعادة الإرسال، وارفض التحقق الفاشل، ثم خزّن دفعة الأحداث بشكل دائم أو ضعها في الطابور قبل الإقرار بالتسليم.

هل ينبغي أن يعيد المنتج محاولة كل طلب Mail Send فاشل؟

لا. أصلح أخطاء الحمولة والمصادقة والتفويض والحجم والمستلِم الدائم بدلًا من إعادة محاولتها. أخّر استجابات 429 حتى إعادة الضبط الموثَّقة، وأعد محاولة إخفاقات الشبكة المؤقتة وأخطاء 5xx بتراجع محدود، وطابِق مهلات الانتهاء الملتبسة قبل إعادة الإرسال.

هل يمكن تجاوز قوائم المنع في SendGrid للبريد المعاملاتي؟

يوفّر SendGrid ضوابط للتجاوز، لكن ينبغي ألا يستخدمها المنتج بشكل روتيني. افصل فئات الرسائل، والتزم بإلغاء الاشتراك أو المنع المنطبق، واشترط تفويضًا موثَّقًا وسجل تدقيق لأي إعادة تفعيل استثنائية أو قرار إرسال خاص بسياسة.

ما الذي ينبغي لفريق تقييمه قبل مقارنة SendGrid وSendHQ؟

قارن حمولات المزوّدين وأحداثهما وضوابط الهوية وقوائم المنع والمتطلبات الإقليمية ومعرّفات المزوّد المخزنة قبل التخطيط للترحيل.

المصادر

تابع التعلّم

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