Suppressions API

تدير Suppressions API قوائم مساحات العمل لعناوين Email وأرقام الهواتف التي لن يرسل Joryio إليها. الحظر بوابة صارمة: ما دام معرّف ما محظورًا في قناة، تُتخطى كل رسالة إليه في تلك القناة، مهما كانت الحملة أو الرحلة التي تحاول الوصول إليه.

تعكس API واجهة Audience ← Suppression Lists في لوحة التحكم. استخدمها لتدقيق المحظورين أو ترحيل قائمة عناوين غير صالحة من منصة أخرى أو احترام طلب موافقة من أنظمتك أو رفع الحظر بعد حل ارتداد دائم.

جميع نقاط النهاية في هذه الصفحة نسبية إلى عنوان الأساس: https://api-eu1.joryio.com. راجع نظرة API العامة.

المصادقة

يُصادَق كل طلب بمفتاح API يحمل نطاق قابلية التسليم ذي الصلة، أو بجلسة dashboard، JWT. بيانات الحظر ضمن مساحة العمل؛ ولا يرى المفتاح أو يحرر إلا قوائم مساحة عمله.

Authorization: Bearer jry_live_your_api_key_here
Content-Type: application/json

النطاقات لكل نقطة نهاية

تحدد القناة النطاق المطلوب. تحتاج نقاط Email نطاق email_suppression:*، وتحتاج SMS وWhatsApp إلى sms_suppression:*.

نقطة النهاية	قناة Email	قناة SMS / WhatsApp
`GET /suppressions`	`email_suppression:read`	`sms_suppression:read`
`GET /suppressions/{identifier}`	`email_suppression:read`	`sms_suppression:read`
`POST /suppressions`	`email_suppression:write`	`sms_suppression:write`
`POST /suppressions/hard-bounce`	`email_suppression:write`	-، Email فقط
`POST /suppressions/import`	`email_suppression:write`	`sms_suppression:write`
`DELETE /suppressions/{identifier}`	`email_suppression:write`	`sms_suppression:write`

المفاهيم الأساسية

اقرأ هذا القسم قبل استدعاء نقاط الكتابة؛ لا معنى لباقي API قبل وضوح الفرق بين reason وsource.

`reason`، لماذا، مقابل `source`، من أين جاء

يحمل كل صف حظر حقلين مستقلين:

reason: لماذا حُظر المعرّف. إحدى القيم: unsubscribe أو hard_bounce أو complaint أو manual.
source: من أين جاء الحظر، أي أصله. إحدى القيم: delivery أو api أو import أو مصدر موافقة مثل unsubscribe_link.

الحقلان متعامدان. قد يأتي hard_bounce من مصادر مختلفة: الارتداد الذي يراه مسار الإرسال لدينا يحمل source: "delivery"، أما الارتداد الذي تؤكده عبر API فيحمل source: "api". يبين reason معنى التسليم/الموافقة، ويبين source مقدار الثقة وهل يدخل في مقاييس السمعة.

أسباب الموافقة مقابل أسباب قابلية التسليم

تنقسم الأسباب الأربعة إلى عائلتين مختلفتي السلوك:

العائلة	الأسباب	المعنى	هل تبقى بعد إعادة الاشتراك؟
الموافقة	`unsubscribe`, `manual`	طلب المستلم، أو طلبت أنت نيابة عنه، عدم الاتصال.	لا؛ قبول جديد يمسحها.
قابلية التسليم	`hard_bounce`, `complaint`	العنوان/الرقم غير صالح أو علّمنا كرسائل مزعجة.	نعم؛ تبقى حتى عند إعادة الاشتراك.

حظر قابلية التسليم حقيقة تقنية عن العنوان لا تفضيل، لذلك لا يرفعه اشتراك المستلم مجددًا. ولا يُرفع إلا بإجراء صريح: DELETE /suppressions/{identifier} أو "clear bounce" من لوحة التحكم أو تغيير جهة الاتصال إلى عنوان Email جديد.

لا يمكنك اختلاق ارتداد

مسارات الكتابة العادية، POST /suppressions وPOST /suppressions/import، تقيّد reason إلى manual أو unsubscribe. لا يمكنها ماديًا إنشاء صف hard_bounce أو complaint. الارتداد شيء تلاحظه المنصة، لا شيء يقرره العميل دون قيد.

المسار الوحيد الذي يسمح بتأكيد ارتداد هو POST /suppressions/hard-bounce، وحتى هناك يحمل الصف source: "api" فلا يختلط بارتداد رأيناه نحن.

الارتدادات الحقيقية فقط تؤثر في السمعة

يحتسب معدل الارتداد المبلغ عنه ومقاييس قابلية التسليم/السمعة في حسابك ارتدادات source: "delivery" فقط، أي ما رآه مسار الإرسال عند طبقة SMTP. الحظر المؤكد من API، source: "api"، أو المستورد، source: "import"، يمنع الإرسال لكنه لا يضخم معدل الارتداد المبلغ عنه. يمكنك بذلك تحميل العناوين المعروفة غير الصالحة مسبقًا لحماية سمعة المرسل من دون تلويث المقياس نفسه.

يتبع الحظر العنوان أو الرقم

يُفهرس الحظر بعنوان Email مطبّع أو رقم هاتف، لكل مساحة عمل، وليس بسجل جهة اتصال. لذلك يغطي عنوان واحد محظور كل جهات الاتصال المكررة التي تشاركه. احظر jane@example.com مرة واحدة فتُمنع جميع جهات الاتصال بهذا العنوان على قناة Email في مساحة العمل.

مرجع reason / source

قيم `reason`

`reason`	العائلة	ينشأ من
`unsubscribe`	موافقة	رابط إلغاء الاشتراك أو `POST /suppressions` أو `POST /suppressions/import`
`manual`	موافقة	إجراء المشغل أو `POST /suppressions` أو `POST /suppressions/import`
`hard_bounce`	قابلية التسليم	مسار الإرسال أو `POST /suppressions/hard-bounce`
`complaint`	قابلية التسليم	مسار الإرسال، feedback loops

قيم `source`

`source`	المعنى	هل يدخل في السمعة؟
`delivery`	رصده مسار الإرسال/الاستقبال لدينا، ارتداد أو شكوى حقيقيان.	نعم
`api`	تم تأكيده عبر REST API.	لا
`import`	حُمّل عبر `POST /suppressions/import`، ترحيل مجمع.	لا
`unsubscribe_link`، ومصادر موافقة أخرى	تغير موافقة يبدأه المستلم.	لا

سرد عمليات الحظر

أعد قائمة مرقمة بالمعرفات المحظورة في قناة.

نقطة النهاية

GET /suppressions

معاملات الاستعلام

المعامل	النوع	الافتراضي	الوصف
`channel`	string	-	`email` أو `sms` أو `whatsapp`. مطلوب.
`reason`	string	-	فلتر اختياري: `unsubscribe` أو `hard_bounce` أو `complaint` أو `manual`.
`limit`	number	`100`	الصفوف في الصفحة، حتى `1000`.
`offset`	number	`0`	إزاحة الترقيم.

طلب مثال

curl -X GET "https://api-eu1.joryio.com/suppressions?channel=email&reason=hard_bounce&limit=50" \
  -H "Authorization: Bearer jry_live_your_api_key"

الاستجابة

{
  "items": [
    {
      "identifier": "dead-address@example.com",
      "channel": "email",
      "identifierType": "email",
      "reason": "hard_bounce",
      "source": "delivery",
      "scope": "global",
      "listId": null,
      "createdAt": "2026-06-30T12:04:11.000Z"
    },
    {
      "identifier": "jane@example.com",
      "channel": "email",
      "identifierType": "email",
      "reason": "unsubscribe",
      "source": "unsubscribe_link",
      "scope": "group",
      "listId": "grp_newsletter",
      "createdAt": "2026-07-02T09:20:00.000Z"
    }
  ],
  "total": 214,
  "limit": 50,
  "offset": 0
}

فحص معرّف واحد

تحقق مما إذا كان معرّف واحد محظورًا في قناة.

نقطة النهاية

GET /suppressions/{identifier}

معامل المسار {identifier} هو عنوان Email أو رقم هاتف بترميز URL.

معاملات الاستعلام

المعامل	النوع	الافتراضي	الوصف
`channel`	string	-	`email` أو `sms` أو `whatsapp`. مطلوب.

طلب مثال

curl -X GET "https://api-eu1.joryio.com/suppressions/dead-address@example.com?channel=email" \
  -H "Authorization: Bearer jry_live_your_api_key"

الاستجابة: محظور

{
  "suppressed": true,
  "identifier": "dead-address@example.com",
  "reason": "hard_bounce",
  "source": "delivery",
  "scope": "global",
  "listId": null,
  "createdAt": "2026-06-30T12:04:11.000Z"
}

الاستجابة: غير محظور

{
  "suppressed": false
}

إضافة حظر

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

نقطة النهاية

POST /suppressions

نص الطلب

الحقل	النوع	مطلوب	الوصف
`channel`	string	نعم	`email` أو `sms` أو `whatsapp`.
`identifier`	string	نعم	عنوان Email أو رقم هاتف لحظره.
`reason`	string	لا	`manual`، الافتراضي، أو `unsubscribe`. مقيّد؛ يُرفض أي شيء آخر.
`scope`	string	لا	`global`، الافتراضي، أو `group`.
`listId`	string	لا	مطلوب عندما يكون `scope` هو `group`: المجموعة/القائمة التي ينطبق عليها الحظر.

يسجل source للصف المنشأ هنا دائمًا كـ api. لا يمكن لنقطة النهاية هذه إنشاء hard_bounce أو complaint.

طلب مثال

curl -X POST https://api-eu1.joryio.com/suppressions \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "identifier": "jane@example.com",
    "reason": "unsubscribe",
    "scope": "group",
    "listId": "grp_newsletter"
  }'

الاستجابة

{
  "identifier": "jane@example.com",
  "channel": "email",
  "identifierType": "email",
  "reason": "unsubscribe",
  "source": "api",
  "scope": "group",
  "listId": "grp_newsletter",
  "createdAt": "2026-07-11T08:15:00.000Z"
}

تأكيد ارتداد دائم

سجل ارتدادًا دائمًا لعنوان Email. هذا هو المسار الوحيد في API الذي يسمح بتأكيد حظر قابلية تسليم، وهو منفصل ومقيّد عمدًا.

لماذا هذه النقطة منفصلة؟

الارتداد شيء يرصده Joryio عادة وقت الإرسال، لا شيء يعلنه المستدعي. فصل تأكيد الارتداد عن مسارات الإضافة/الاستيراد يمنع الاختلاق العرضي أو غير المتحفظ.
لأنك تؤكد بدل أن نرصد، يحمل الصف source: "api". يمنع الإرسال تمامًا كارتداد حقيقي لكنه لا يختلط بما رأيناه نحن ولا يدخل في معدل الارتداد المبلغ عنه أو مقاييس سمعة المرسل.
هو Email فقط؛ لا مكافئ لأرقام الهاتف، إذ إن عدم تسليم SMS/WhatsApp يُنمذج بطريقة مختلفة.

نقطة النهاية

POST /suppressions/hard-bounce

نص الطلب

الحقل	النوع	مطلوب	الوصف
`identifier`	string	نعم	عنوان Email الذي ارتد ارتدادًا دائمًا.

تكون القناة email ضمنية. يسجل الصف بـ reason: "hard_bounce" وsource: "api".

طلب مثال

curl -X POST https://api-eu1.joryio.com/suppressions/hard-bounce \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "no-such-mailbox@example.com"
  }'

الاستجابة

{
  "identifier": "no-such-mailbox@example.com",
  "channel": "email",
  "identifierType": "email",
  "reason": "hard_bounce",
  "source": "api",
  "scope": "global",
  "listId": null,
  "createdAt": "2026-07-11T08:20:00.000Z"
}

الاستيراد المجمع

حمّل قائمة حظر قائمة، مثلًا عند الترحيل من منصة أخرى.

نقطة النهاية

POST /suppressions/import

نص الطلب

الحقل	النوع	مطلوب	الوصف
`channel`	string	نعم	`email` أو `sms` أو `whatsapp`.
`entries`	array	نعم	حتى `5000` كائن، كل واحد `{ identifier, reason? }`.

يُقيّد reason لكل إدخال إلى manual، الافتراضي، أو unsubscribe؛ ويحوّل أي قيمة أخرى إلى manual. يسجل كل صف مستورد بـ source: "import". ومثل نقطة الإضافة، لا يستطيع الاستيراد إنشاء ارتداد أو شكوى.

طلب مثال

curl -X POST https://api-eu1.joryio.com/suppressions/import \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "entries": [
      { "identifier": "old-dead-1@example.com" },
      { "identifier": "opted-out@example.com", "reason": "unsubscribe" },
      { "identifier": "old-dead-2@example.com" }
    ]
  }'

الاستجابة

{
  "channel": "email",
  "received": 3,
  "imported": 3,
  "skipped": 0,
  "source": "import"
}

إزالة حظر، إلغاء الحظر

أزل حظرًا ليسمح Joryio بالإرسال إلى المعرّف مجددًا.

نقطة النهاية

DELETE /suppressions/{identifier}

معاملات الاستعلام

المعامل	النوع	الافتراضي	الوصف
`channel`	string	-	`email` أو `sms` أو `whatsapp`. مطلوب.

تحذير

يؤدي ذلك إلى إزالة كل صفوف الحظر للمعرف في القناة ومساحة العمل، بما فيها صف hard_bounce أو complaint. هذا رفع صريح من مشغّل/API: إلغاء حظر العنوان هو بالضبط طريقة مسح ارتداد دائم حُل. لا ترفع حظر قابلية التسليم إلا عندما تعرف أن المشكلة الأساسية حُلّت، وإلا قد ترسل إلى عنوان غير صالح وتضر بسمعة المرسل.

طلب مثال

curl -X DELETE "https://api-eu1.joryio.com/suppressions/no-such-mailbox@example.com?channel=email" \
  -H "Authorization: Bearer jry_live_your_api_key"

الاستجابة

{
  "identifier": "no-such-mailbox@example.com",
  "removed": 2
}

يمثل removed عدد صفوف الحظر المحذوفة؛ فقد يحمل معرّف واحد صف موافقة بنطاق مجموعة وصف قابلية تسليم عالميًا في وقت واحد.

ترحيل قائمة حظر قائمة

عند الانتقال إلى Joryio من منصة Email أو SMS أخرى، أحضر قائمة الحظر في اليوم الأول كي لا تعيد الإرسال إلى عناوين تعرف أنها غير صالحة أو ملغية الاشتراك.

استورد القائمة كاملة عبر POST /suppressions/import. تصل الإدخالات كـ manual، أو unsubscribe إن علّمتها، مع source: "import". تمنع الإرسال وتحمي سمعة المرسل في أول إرسال، من دون تضخيم معدل الارتداد المبلغ عنه لأن الصفوف المستوردة لا تدخل في السمعة.
فقط إذا احتجت تحديدًا إلى أن تُبلغ هذه العناوين كارتدادات، مثل الاستمرار في تحليلات الارتداد بعد الترحيل، أكدها فرديًا عبر POST /suppressions/hard-bounce. ستبقى source: "api"، فتمنع الإرسال وتظهر كارتدادات في قائمة الحظر دون أن تدخل كارتدادات رصدناها.

في معظم عمليات الترحيل، الخطوة 1 وحدها هي الاختيار الصحيح: توقف الإرسال وتحافظ على نظافة مقاييس السمعة.

استجابات الأخطاء

تشترك الأخطاء في الشكل القياسي. لا توجد مفردات مستقلة لرموز خطأ قابلة للقراءة آليًا؛ استخدم حالة HTTP وحقل message. راجع استجابة الخطأ في نظرة API. تضيف أخطاء التحقق، 400، مصفوفة errors برسالة لكل حقل فاشل:

{
  "statusCode": 400,
  "message": "Bad Request Exception",
  "timestamp": "2026-07-12T09:00:00.000Z",
  "path": "/suppressions",
  "errors": [
    "reason must be one of the following values: manual, unsubscribe"
  ]
}

ملحوظة مهمة: تفرض API نطاقات دقيقة حسب القناة. يحصل مفتاح API الذي يحمل نطاق SMS فقط على 403 عند لمس حظر Email، والعكس:

{
  "statusCode": 403,
  "message": "API key missing required scope 'email_suppression:write' for channel 'email'",
  "timestamp": "2026-07-12T09:00:00.000Z",
  "path": "/suppressions"
}

المصادقة​

النطاقات لكل نقطة نهاية​

المفاهيم الأساسية​

reason، لماذا، مقابل source، من أين جاء​

أسباب الموافقة مقابل أسباب قابلية التسليم​

لا يمكنك اختلاق ارتداد​

الارتدادات الحقيقية فقط تؤثر في السمعة​

يتبع الحظر العنوان أو الرقم​

مرجع reason / source​

قيم reason​

قيم source​

سرد عمليات الحظر​

نقطة النهاية​

معاملات الاستعلام​

طلب مثال​

الاستجابة​

فحص معرّف واحد​

نقطة النهاية​

معاملات الاستعلام​

طلب مثال​

الاستجابة: محظور​

الاستجابة: غير محظور​

إضافة حظر​

نقطة النهاية​

نص الطلب​

طلب مثال​

الاستجابة​

تأكيد ارتداد دائم​

لماذا هذه النقطة منفصلة؟​

نقطة النهاية​

نص الطلب​

طلب مثال​

الاستجابة​

الاستيراد المجمع​

نقطة النهاية​

نص الطلب​

طلب مثال​

الاستجابة​

إزالة حظر، إلغاء الحظر​

نقطة النهاية​

معاملات الاستعلام​

طلب مثال​

الاستجابة​

ترحيل قائمة حظر قائمة​

استجابات الأخطاء​

الخطوات التالية​

المصادقة

النطاقات لكل نقطة نهاية

المفاهيم الأساسية

`reason`، لماذا، مقابل `source`، من أين جاء

أسباب الموافقة مقابل أسباب قابلية التسليم

لا يمكنك اختلاق ارتداد

الارتدادات الحقيقية فقط تؤثر في السمعة

يتبع الحظر العنوان أو الرقم

مرجع reason / source

قيم `reason`

قيم `source`

سرد عمليات الحظر

نقطة النهاية

معاملات الاستعلام

طلب مثال

الاستجابة

فحص معرّف واحد

نقطة النهاية

معاملات الاستعلام

طلب مثال

الاستجابة: محظور

الاستجابة: غير محظور

إضافة حظر

نقطة النهاية

نص الطلب

طلب مثال

الاستجابة

تأكيد ارتداد دائم

لماذا هذه النقطة منفصلة؟

نقطة النهاية

نص الطلب

طلب مثال

الاستجابة

الاستيراد المجمع

نقطة النهاية

نص الطلب

طلب مثال

الاستجابة

إزالة حظر، إلغاء الحظر

نقطة النهاية

معاملات الاستعلام

طلب مثال

الاستجابة

ترحيل قائمة حظر قائمة

استجابات الأخطاء

الخطوات التالية