MailLandDocs
التسويق

الشرائح

إنشاء شرائح ديناميكية بناءً على سمات المشتركين وسلوكهم

الشرائح هي مجموعات ديناميكية من المشتركين تُعرَّف بواسطة شروط محددة. على عكس القوائم الثابتة، تتحدث الشرائح تلقائيًا مع تغيُّر بيانات المشتركين. استخدم الشرائح لاستهداف الحملات بجماهير محددة بناءً على السمات والتفاعل والسلوك.

أنواع التطابق

نوع التطابقالقيمةالوصف
All0يجب أن تتطابق جميع الشروط (منطق AND)
Any1يمكن لأي شرط أن يتطابق (منطق OR)

إنشاء شريحة

POST https://api.mail.land/v1/marketing/segments
Create segment request
{
  "name": "Active Engaged Users",
  "description": "Users who opened or clicked in last 30 days",
  "matchType": "All",
  "conditions": [
    {
      "field": "lastemailopenedat",
      "operator": "inlast",
      "value": "30"
    },
    {
      "field": "status",
      "operator": "equals",
      "value": "Active"
    }
  ]
}
الحقلالنوعمطلوبالوصف
namestringنعماسم الشريحة (فريد لكل مساحة عمل)
descriptionstringلاوصف الشريحة
matchTypestringلاAll (افتراضي) أو Any
conditionsarrayنعمشرط واحد على الأقل
Create a segment
curl -X POST https://api.mail.land/v1/marketing/segments \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Active Engaged Users",
    "matchType": "All",
    "conditions": [
      { "field": "lastemailopenedat", "operator": "inlast", "value": "30" },
      { "field": "status", "operator": "equals", "value": "Active" }
    ]
  }'

الاستجابة

Segment response
{
  "id": "0qe306asbapwvd",
  "name": "Active Engaged Users",
  "description": "Users who opened or clicked in last 30 days",
  "matchType": "all",
  "matchTypeName": "All",
  "conditionsCount": 2,
  "subscriberCount": 450,
  "createdAt": "2026-02-17T12:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

تُعيد الاستجابات matchType بأحرف صغيرة ("all" / "any") حتى وإن كان طلب الإنشاء/التحديث يقبل "All"/"Any".

حقول الشرط المبنية على الفتح/النقر (emailsopened، lastemailopenedat، إلخ) تتضمن نشاطاً آلياً، الجلب المسبق لحماية خصوصية بريد Apple وماسحات الروابط الأمنية، وهو غير مُصفّى حالياً.

توجد أيضاً نقطة نهاية غير موثَّقة GET /{id}/preview، تُعيد عيّنة من المشتركين الذين يطابقون حالياً شروط الشريحة.

حقول الشرط

الحقول النصية

الحقول: email، firstname، lastname، company، source، phone

المعاملالوصفالقيمة مطلوبة
equalsتطابق تامنعم
notequalsلا يساوينعم
containsيحتوي على نص فرعينعم
notcontainsلا يحتوي علىنعم
startswithيبدأ بـنعم
endswithينتهي بـنعم
isemptyالحقل فارغلا
isnotemptyالحقل غير فارغلا

الحقول الرقمية

الحقول: emailssent، emailsopened، emailsclicked

المعاملالوصفالقيمة مطلوبةالقيمة2 مطلوبة
equalsيساوينعملا
notequalsلا يساوينعملا
greaterthanأكبر مننعملا
greaterthanorequalأكبر من أو يساوينعملا
lessthanأقل مننعملا
lessthanorequalأقل من أو يساوينعملا
betweenبين قيمتيننعمنعم

حقول التاريخ

الحقول: createdat، subscribedat، lastemailsentat، lastemailopenedat، lastemailclickedat

المعاملالوصفالقيمة مطلوبة
equalsفي تاريخ محددنعم (تاريخ ISO)
beforeقبل التاريخنعم (تاريخ ISO)
afterبعد التاريخنعم (تاريخ ISO)
onorbeforeفي أو قبلنعم (تاريخ ISO)
onorafterفي أو بعدنعم (تاريخ ISO)
betweenبين تاريخيننعم (value + value2)
inlastفي آخر N أيامنعم (عدد صحيح للأيام)
isnullالتاريخ غير محددلا
isnotnullالتاريخ محددلا

الحقول التعدادية

الحقل: status

المعاملالوصفالقيم
equalsيساوي الحالةActive، Unsubscribed، Bounced، Complained
notequalsلا يساوينفس القيم

أمثلة على الشروط

Email domain filter
{ "field": "email", "operator": "contains", "value": "example.com" }
High engagement filter
{ "field": "emailssent", "operator": "between", "value": "10", "value2": "50" }
Recent clickers
{ "field": "lastemailclickedat", "operator": "inlast", "value": "7" }
Missing first name
{ "field": "firstname", "operator": "isempty" }

الحصول على بيانات تعريف الشريحة

استرداد جميع الحقول والمعاملات والقيم التعدادية المتاحة لبناء شروط الشريحة:

GET https://api.mail.land/v1/marketing/segments/metadata/fields
Get segment metadata
curl https://api.mail.land/v1/marketing/segments/metadata/fields \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Metadata response
{
  "fields": [
    {
      "name": "email",
      "label": "Email",
      "type": "string",
      "operators": ["equals", "notequals", "contains", "notcontains", "startswith", "endswith", "isempty", "isnotempty"],
      "enumValues": null
    },
    {
      "name": "status",
      "label": "Status",
      "type": "enum",
      "operators": ["equals", "notequals"],
      "enumValues": ["Active", "Unsubscribed", "Bounced", "Complained"]
    }
  ]
}

قائمة الشرائح

GET https://api.mail.land/v1/marketing/segments
المعاملالنوعالافتراضيالوصف
cursorstring-مؤشر معتم من nextCursor للصفحة السابقة. احذفه للصفحة الأولى.
limitint20العناصر في الصفحة
searchstring-البحث بالاسم أو الوصف
sortBystring-حقل الترتيب
sortDescboolfalseالترتيب تنازلياً
List segments
curl "https://api.mail.land/v1/marketing/segments?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

الحصول على تفاصيل الشريحة

GET https://api.mail.land/v1/marketing/segments/{id}

يعيد الشريحة الكاملة مع شروطها:

Get segment details
curl https://api.mail.land/v1/marketing/segments/0qe306asbapwvd \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Segment detail response
{
  "id": "0qe306asbapwvd",
  "name": "Active Engaged Users",
  "description": "Users who engaged in last 30 days",
  "matchType": "all",
  "matchTypeName": "All",
  "conditionsCount": 2,
  "subscriberCount": 450,
  "conditions": [
    {
      "field": "lastemailopenedat",
      "operator": "inlast",
      "value": "30",
      "value2": null
    },
    {
      "field": "status",
      "operator": "equals",
      "value": "Active",
      "value2": null
    }
  ],
  "cachedCount": 450,
  "cachedAt": "2026-02-17T10:00:00Z",
  "createdAt": "2026-01-10T08:00:00Z",
  "updatedAt": "2026-02-17T10:00:00Z"
}

معاينة الشروط

معاينة نتيجة الشروط قبل إنشاء الشريحة. يقتصر تقييم الشريحة دائماً على المشتركين ذوي الحالة Active، لذا فإن شرطاً مثل status notequals Active لا يطابق أحداً.

POST https://api.mail.land/v1/marketing/segments/preview
Preview request
{
  "conditions": [
    { "field": "lastemailopenedat", "operator": "inlast", "value": "30" }
  ],
  "matchType": "All"
}
Preview segment conditions
curl -X POST https://api.mail.land/v1/marketing/segments/preview \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      { "field": "lastemailopenedat", "operator": "inlast", "value": "30" }
    ],
    "matchType": "All"
  }'
Preview response
{
  "count": 450,
  "sampleEmails": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
}

الحصول على عدد الشريحة

GET https://api.mail.land/v1/marketing/segments/{id}/count
Get segment count
curl https://api.mail.land/v1/marketing/segments/0qe306asbapwvd/count \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Count response
{
  "segmentId": "0qe306asbapwvd",
  "count": 450
}

تحديث ذاكرة التخزين المؤقت للشريحة

إجبار إعادة حساب المشتركين المطابقين:

POST https://api.mail.land/v1/marketing/segments/{id}/refresh
Refresh segment cache
curl -X POST https://api.mail.land/v1/marketing/segments/0qe306asbapwvd/refresh \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Refresh response
{
  "segmentId": "0qe306asbapwvd",
  "count": 460,
  "refreshedAt": "2026-02-17T12:30:00Z"
}

تكرار شريحة

POST https://api.mail.land/v1/marketing/segments/{id}/duplicate?name=Copy%20of%20Segment

ينشئ شريحة جديدة بشروط مستنسخة. المعامل name اختياري.

Duplicate a segment
curl -X POST "https://api.mail.land/v1/marketing/segments/0qe306asbapwvd/duplicate?name=Copy%20of%20Segment" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

تحديث شريحة

PUT https://api.mail.land/v1/marketing/segments/{id}

يتطابق نص الطلب مع طلب الإنشاء. يؤدي تحديث الشريحة إلى تحديث عددها المخزن مؤقتًا تلقائيًا.

Update a segment
curl -X PUT https://api.mail.land/v1/marketing/segments/0qe306asbapwvd \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Active Engaged Users (Updated)",
    "matchType": "All",
    "conditions": [
      { "field": "lastemailopenedat", "operator": "inlast", "value": "14" },
      { "field": "status", "operator": "equals", "value": "Active" }
    ]
  }'

حذف شريحة

DELETE https://api.mail.land/v1/marketing/segments/{id}

يؤدي حذف شريحة إلى فصلها عن أي حملة بحالة Draft أو Scheduled تستهدفها (يُمسَح segmentId الخاص بالحملة)، فتصبح بلا جمهور: إرسالها يُرجِع 422 أو يُسلَّم إلى لا أحد. أما الحملة التي هي بالفعل في حالة Sending فلا تتأثر، لأن مستلميها قد تم تحديدهم مسبقاً.

Delete a segment
curl -X DELETE https://api.mail.land/v1/marketing/segments/0qe306asbapwvd \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

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

الحالةالرمزالوصف
400VALIDATION_FAILEDالاسم أو الشروط غير صالحة
400INVALID_REQUESTاسم الشريحة موجود مسبقًا
403FORBIDDENصلاحيات غير كافية
404RESOURCE_NOT_FOUNDالشريحة غير موجودة

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

  • الحملات: استهداف الحملات بالشرائح
  • الأتمتة: لا تُشغَّل الأتمتة حالياً بناءً على عضوية الشريحة
  • المشتركون: إدارة جهات الاتصال في شرائحك

القوائم البريدية

تنظيم المشتركين في قوائم بريدية لحملات مستهدفة

الأتمتة

إعداد تسلسلات بريد إلكتروني تلقائية قائمة على المحفزات بناءً على سلوك المشتركين

في هذه الصفحة

أنواع التطابقإنشاء شريحةالاستجابةحقول الشرطالحقول النصيةالحقول الرقميةحقول التاريخالحقول التعداديةأمثلة على الشروطالحصول على بيانات تعريف الشريحةقائمة الشرائحالحصول على تفاصيل الشريحةمعاينة الشروطالحصول على عدد الشريحةتحديث ذاكرة التخزين المؤقت للشريحةتكرار شريحةتحديث شريحةحذف شريحةاستجابات الخطأالخطوات التالية