قوائم الحظر

إدارة قوائم الحظر لمنع الإرسال إلى العناوين غير الصالحة أو الملغاة اشتراكها أو التي قدّمت شكاوى

تمنع قائمة الحظر إرسال رسائل البريد الإلكتروني إلى العناوين التي ارتدّت أو ألغت اشتراكها أو قدّمت شكاوى. تُدير MailLand الحظر تلقائيًا من أحداث الارتداد والشكاوى، ويمكنكم إضافة الإدخالات أو إزالتها يدويًا عبر API.

أنواع الحظر

النوع	القيمة	الوصف	النطاق الافتراضي
`HardBounce`	1	فشل تسليم دائم	Global (دائمًا)
`SoftBounce`	2	فشل مؤقت (حظر تسويقي لمدة 30 يومًا، ولا يتصاعد إلا بعد 3 ارتدادات مؤهلة على الأقل خلال 7 أيام على الأقل)	Marketing (انتهاء صلاحية 30 يومًا)
`Complaint`	3	أبلغ المستلم عن البريد كرسالة مزعجة	Global (دائمًا)
`Unsubscribe`	4	ألغى المستلم اشتراكه	يعتمد على نوع الرسالة
`Manual`	5	مُضاف يدويًا عبر API أو لوحة التحكم	أي نطاق
`Invalid`	6	تنسيق بريد إلكتروني غير صالح	Global (دائمًا)
`SpamTrap`	7	عنوان تله بريد مزعج معروف	Global (دائمًا)
`RoleAddress`	8	بريد إلكتروني مرتبط بدور (info@، admin@، إلخ)	Global (دائمًا)

نطاقات الحظر

تتحكم النطاقات في أنواع رسائل البريد الإلكتروني المحظورة:

النطاق	القيمة	السلوك
`Global`	0	يحظر جميع رسائل البريد الإلكتروني (التعاملاتية والتسويقية)
`Marketing`	1	يحظر رسائل التسويق؛ لا تزال رسائل المعاملات تُسلَّم
`Transactional`	2	يحظر رسائل المعاملات فقط (نادر)
`List`	3	يحظر رسائل قائمة بريدية محددة فقط

قيود النطاق:

HardBounce، Complaint، Invalid، SpamTrap، RoleAddress ← نطاق Global فقط
SoftBounce ← عادةً نطاق Marketing
Unsubscribe ← Global أو Marketing أو List (ليس Transactional)
Manual ← أي نطاق

قائمة إدخالات الحظر

GET https://api.mail.land/v1/transactional/suppressions

المصادقة عبر Authorization: Bearer <token> أو X-API-Key: <api key>.

List suppressions

curl https://api.mail.land/v1/transactional/suppressions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

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

المعامل	النوع	الافتراضي	الوصف
`cursor`	string	-	مؤشر معتم من `nextCursor` للصفحة السابقة. احذفه للصفحة الأولى.
`limit`	int	50	العناصر في الصفحة (بحد أقصى 100)
`search`	string	-	تصفية حسب عنوان البريد الإلكتروني
`type`	SuppressionType	-	تصفية حسب النوع
`scope`	SuppressionScope	-	تصفية حسب النطاق
`mailingListId`	string	-	المعرّف العام للقائمة البريدية، يُحلَّل داخل مستأجرك. المعرّف غير المعروف أو التابع لمستأجر آخر أو الرقمي يُعيد `404`.
`fromDate`	datetime	قبل 90 يومًا	تاريخ البداية
`toDate`	datetime	الآن	تاريخ النهاية
`sortBy`	string	`CreatedAt`	حقل الترتيب
`sortDescending`	bool	true	اتجاه الترتيب

Suppression list response

{
  "items": [
    {
      "id": "k3v9x2m8q1w7z4",
      "email": "[email protected]",
      "suppressionType": "hardBounce",
      "scope": "global",
      "mailingListId": null,
      "mailingListName": null,
      "expiresAt": null,
      "reason": "550 5.1.1 The email account does not exist",
      "bounceType": "Hard",
      "bounceCategory": "invalid_recipient",
      "bounceCount": 1,
      "lastBounceAt": "2026-02-17T12:00:00Z",
      "unsubscribeSource": null,
      "campaignId": null,
      "subscriberId": null,
      "source": "webhook",
      "notes": null,
      "createdAt": "2026-02-17T12:00:01Z",
      "isLocked": false,
      "lockedReason": null
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

الحقول mailingListId وcampaignId وsubscriberId هي المعرّف العام للمورد المرتبط، محلولًا داخل مستأجرك، أبدًا المعرّف الرقمي الداخلي. تكون كل واحدة منها null عندما لا يوجد رابط من هذا النوع، أو عندما يكون المورد المرتبط قد حُذف منذ ذلك الحين.

إحصاءات الحظر

احصلوا على ملخص لقائمة الحظر الخاصة بكم:

GET https://api.mail.land/v1/transactional/suppressions/stats

Get suppression stats

curl https://api.mail.land/v1/transactional/suppressions/stats \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Stats response

{
  "totalCount": 5000,
  "globalCount": 3000,
  "marketingCount": 1500,
  "transactionalCount": 200,
  "listCount": 300,
  "hardBounceCount": 2000,
  "softBounceCount": 1500,
  "complaintCount": 500,
  "unsubscribeCount": 700,
  "manualCount": 200,
  "invalidCount": 50,
  "spamTrapCount": 30,
  "roleAddressCount": 20,
  "expiringCount": 85,
  "lastSuppression": "2026-02-17T12:00:01Z"
}

يُظهر expiringCount الارتدادات الناعمة التي ستنتهي صلاحيتها خلال الأيام السبعة القادمة.

التحقق من حظر بريد إلكتروني

فحص مفرد

GET https://api.mail.land/v1/transactional/suppressions/[email protected]&messageType=Marketing

Check suppression

curl "https://api.mail.land/v1/transactional/suppressions/[email protected]&messageType=Marketing" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

المعامل	النوع	الافتراضي	الوصف
`email`	string	-	عنوان البريد الإلكتروني (مطلوب)
`messageType`	string	`Marketing`	`Marketing` أو `Transactional`
`mailingListId`	string	-	المعرّف العام للقائمة البريدية، يُحلَّل داخل مستأجرك. المعرّف غير المعروف أو التابع لمستأجر آخر أو الرقمي يُعيد `404`.

Check response

{
  "email": "[email protected]",
  "isSuppressed": true,
  "messageType": "Marketing"
}

فحص جماعي

فحص ما يصل إلى 1٬000 بريد إلكتروني دفعةً واحدة:

POST https://api.mail.land/v1/transactional/suppressions/check-bulk

Bulk check suppressions

curl -X POST https://api.mail.land/v1/transactional/suppressions/check-bulk \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"emails":["[email protected]","[email protected]","[email protected]"],"messageType":"Marketing","mailingListId":null}'

Bulk check request

{
  "emails": ["[email protected]", "[email protected]", "[email protected]"],
  "messageType": "Marketing",
  "mailingListId": null
}

Bulk check response

{
  "suppressedEmails": ["[email protected]"]
}

إضافة حظر

POST https://api.mail.land/v1/transactional/suppressions

Add suppression

curl -X POST https://api.mail.land/v1/transactional/suppressions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","suppressionType":"Manual","scope":"Global","reason":"Customer requested removal from all lists","notes":"Ticket #4521"}'

Add suppression request

{
  "email": "[email protected]",
  "suppressionType": "Manual",
  "scope": "Global",
  "reason": "Customer requested removal from all lists",
  "notes": "Ticket #4521"
}

الحقل	النوع	مطلوب	الافتراضي	الوصف
`email`	string	نعم	-	عنوان البريد الإلكتروني (بحد أقصى 255 حرفًا)
`suppressionType`	string	لا	`Manual`	نوع الحظر
`scope`	string	لا	`Global`	نطاق الحظر
`mailingListId`	string	لا	-	المعرّف العام للقائمة البريدية، يُحلَّل داخل مستأجرك. مطلوب إذا كان النطاق `List`؛ المعرّف غير المعروف أو التابع لمستأجر آخر أو الرقمي يُعيد `404`.
`reason`	string	لا	-	السبب (بحد أقصى 500 حرف)
`notes`	string	لا	-	ملاحظات داخلية

يُعيد 201 Created مع كائن الحظر الكامل. رأس Location هو /v1/transactional/suppressions: مسار القائمة نفسه، إذ لا يوجد مسار للجلب حسب المعرّف. استخدم حقل id في نص الاستجابة لتحديد الحظر المُنشأ، ونقطتَي قائمة إدخالات الحظر أو التحقق من حظر بريد إلكتروني أدناه للبحث عنه.

الإضافة الجماعية

إضافة ما يصل إلى 1٬000 حظر دفعةً واحدة:

POST https://api.mail.land/v1/transactional/suppressions/bulk

Bulk add suppressions

curl -X POST https://api.mail.land/v1/transactional/suppressions/bulk \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"emails":[{"email":"[email protected]","suppressionType":"Manual","scope":"Global","reason":"Cleanup"},{"email":"[email protected]","suppressionType":"Manual","scope":"Marketing"}]}'

Bulk add request

{
  "emails": [
    { "email": "[email protected]", "suppressionType": "Manual", "scope": "Global", "reason": "Cleanup" },
    { "email": "[email protected]", "suppressionType": "Manual", "scope": "Marketing" }
  ]
}

Bulk add response

{
  "totalCount": 2,
  "addedCount": 2,
  "skippedCount": 0,
  "skippedEmails": [],
  "message": "Added 2 suppressions"
}

تُتجاوز رسائل البريد الإلكتروني الموجودة بالفعل في قائمة الحظر (لا تتكرر).

الاستيراد من CSV

من محتوى نصي

POST https://api.mail.land/v1/transactional/suppressions/import

Import suppressions from CSV text

curl -X POST https://api.mail.land/v1/transactional/suppressions/import \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"csvContent":"[email protected]\[email protected]\[email protected]","defaultReason":"Imported from legacy system","suppressionType":"Manual","scope":"Global"}'

CSV import request

{
  "csvContent": "[email protected]\n[email protected]\n[email protected]",
  "defaultReason": "Imported from legacy system",
  "suppressionType": "Manual",
  "scope": "Global"
}

من رفع ملف

POST https://api.mail.land/v1/transactional/suppressions/import-file

Import suppressions from file

curl -X POST "https://api.mail.land/v1/transactional/suppressions/import-file?scope=List&mailingListId=123" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -F "[email protected]"

scope وmailingListId معاملا استعلام، وليسا حقلي نموذج: أي حقل نموذج بأحد هذين الاسمين يُتجاهل بصمت، لذا يفشل استيراد بنطاق List مُرسَل كحقل نموذج بخطأ 400. mailingListId هو المعرّف العام للقائمة، يُحلَّل داخل مستأجرك؛ المعرّف غير المعروف أو التابع لمستأجر آخر أو الرقمي يُعيد 404.

قم برفع ملف .csv (بحد أقصى 5 ميغابايت) يحتوي على عناوين بريد إلكتروني مفصولة بفواصل أو أسطر جديدة. يُتخطى سطر العنوان الذي يحتوي على "email" تلقائيًا.

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

المعامل	النوع	الوصف
`file`	file (حقل نموذج متعدد الأجزاء)	ملف CSV (بحد أقصى 5 ميغابايت، امتداد `.csv` مطلوب)
`scope`	string (استعلام)	نطاق الحظر (الافتراضي: `Global`)
`mailingListId`	string (استعلام)	المعرّف العام للقائمة البريدية، يُحلَّل داخل مستأجرك. مطلوب إذا كان النطاق `List`؛ المعرّف غير المعروف أو التابع لمستأجر آخر أو الرقمي يُعيد `404`.

Import result

{
  "totalRows": 1000,
  "importedCount": 950,
  "skippedCount": 40,
  "invalidCount": 10,
  "invalidEmails": ["not-an-email", "missing-domain@", "..."],
  "errors": [],
  "message": "Imported 950 emails. 40 already existed. 10 invalid."
}

تُظهر قائمة invalidEmails ما يصل إلى 10 إدخالات غير صالحة. تُحسب رسائل البريد الإلكتروني الموجودة مسبقًا ضمن skippedCount وليس ضمن الأخطاء.

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

نزّلوا قائمة الحظر الخاصة بكم بصيغة CSV:

GET https://api.mail.land/v1/transactional/suppressions/export

Export suppressions

curl https://api.mail.land/v1/transactional/suppressions/export \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -o suppressions.csv

المعامل	النوع	الوصف
`type`	SuppressionType	تصفية حسب النوع
`scope`	SuppressionScope	تصفية حسب النطاق
`mailingListId`	string	المعرّف العام للقائمة البريدية، يُحلَّل داخل مستأجرك. المعرّف غير المعروف أو التابع لمستأجر آخر أو الرقمي يُعيد `404`.

يُعيد ملف CSV بالأعمدة التالية: email، type، scope، mailing_list، reason، bounce_count، source، created_at، expires_at. محدود بـ 100٬000 سطر.

حذف حظر

حسب المعرّف

DELETE https://api.mail.land/v1/transactional/suppressions/{id}

Delete suppression by ID

curl -X DELETE https://api.mail.land/v1/transactional/suppressions/k3v9x2m8q1w7z4 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

حسب البريد الإلكتروني

DELETE https://api.mail.land/v1/transactional/suppressions/[email protected]

Delete suppression by email

curl -X DELETE "https://api.mail.land/v1/transactional/suppressions/[email protected]" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

المعامل	النوع	الوصف
`email`	string	البريد الإلكتروني لإلغاء الحظر (مطلوب)
`scope`	SuppressionScope	إزالة هذا النطاق فقط
`mailingListId`	string	إزالة لهذه القائمة البريدية فقط، معرّفها العام، يُحلَّل داخل مستأجرك. المعرّف غير المعروف أو التابع لمستأجر آخر أو الرقمي يُعيد `404`.

يُعيد 204 No Content عند النجاح، و404 إذا لم يُوجد.

الحظر المقفل

لا يمكن حذف بعض إدخالات الحظر لحماية سمعة المُرسِل والامتثال للوائح مكافحة البريد المزعج:

النوع المقفل	السبب
`Complaint`	شكوى بريد مزعج: متطلب امتثال
`SpamTrap`	تله بريد مزعج معروف: حماية قابلية التسليم
إلغاء اشتراك عبر `FeedbackLoop`	حلقة ملاحظات ISP
إلغاء اشتراك عبر `OneClick`	إلغاء اشتراك بنقرة واحدة RFC 8058
إلغاء اشتراك عبر `ManualLink`	أكّد المستخدم إلغاء الاشتراك
إلغاء اشتراك عبر `Preference`	اختيار مركز التفضيلات

تُعيد محاولة حذف حظر مقفل الاستجابة التالية:

403 Forbidden

{
  "code": "SUPPRESSION_LOCKED",
  "message": "Cannot delete: Spam complaint - compliance requirement",
  "details": {
    "lockedReason": "Spam complaint - compliance requirement"
  }
}

سيُلحق حذف إدخالات الحظر المستندة إلى الشكاوى وإعادة الإرسال إلى تلك العناوين ضررًا بسمعتكم كمُرسِل وقد ينتهك قوانين مكافحة البريد المزعج. هذه الإدخالات مقفلة لحمايتكم.

مصادر إلغاء الاشتراك

عند إلغاء المستلم لاشتراكه، يُسجَّل المصدر:

المصدر	القيمة	الوصف	مقفل
`ListUnsubscribeHeader`	0	ترويسة List-Unsubscribe من RFC 8058	لا
`ListUnsubscribeMail`	1	إلغاء اشتراك عبر mailto:	لا
`WebForm`	2	صفحة إلغاء اشتراك ويب	لا
`Api`	3	استدعاء API	لا
`Admin`	4	لوحة الإدارة	لا
`FeedbackLoop`	5	حلقة ملاحظات ISP	نعم
`OneClick`	6	POST بنقرة واحدة RFC 8058	نعم
`ManualLink`	7	المستخدم أكّد عبر رابط	نعم
`Preference`	8	اختيار مركز التفضيلات	نعم

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

الحالة	الرمز	الوصف
`400`	`INVALID_REQUEST`	فشل التحقق (بريد إلكتروني أو نطاق أو نوع غير صالح)
`400`	`INVALID_EMAIL_FORMAT`	تنسيق عنوان البريد الإلكتروني غير صالح
`400`	`CONTENT_TOO_LARGE`	حجم ملف CSV يتجاوز 5 ميغابايت
`403`	`SUPPRESSION_LOCKED`	لا يمكن حذف حظر مقفل
`404`	`RESOURCE_NOT_FOUND`	الحظر غير موجود، أو `mailingListId` المُرسَل لا يُسمّي أي قائمة بريدية في مستأجرك

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

الارتدادات: فهم أنواع الارتداد والحظر التلقائي
نظرة عامة على قابلية التسليم: مراقبة سمعة المُرسِل
أحداث ويب هوك: استقبال أحداث message.bounced (suppression.added/suppression.removed مُعرَّفان في الكتالوج لكن لا يُصدَران اليوم)

قوائم الحظر

أنواع الحظرنسخ رابط القسم

نطاقات الحظرنسخ رابط القسم

قائمة إدخالات الحظرنسخ رابط القسم

معاملات الاستعلامنسخ رابط القسم

إحصاءات الحظرنسخ رابط القسم

التحقق من حظر بريد إلكترونينسخ رابط القسم

فحص مفردنسخ رابط القسم

فحص جماعينسخ رابط القسم

إضافة حظرنسخ رابط القسم

الإضافة الجماعيةنسخ رابط القسم

الاستيراد من CSVنسخ رابط القسم

من محتوى نصينسخ رابط القسم

من رفع ملفنسخ رابط القسم

تصدير قائمة الحظرنسخ رابط القسم

حذف حظرنسخ رابط القسم

حسب المعرّفنسخ رابط القسم

حسب البريد الإلكترونينسخ رابط القسم

الحظر المقفلنسخ رابط القسم

مصادر إلغاء الاشتراكنسخ رابط القسم

استجابات الخطأنسخ رابط القسم

الخطوات التاليةنسخ رابط القسم

في هذه الصفحة