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

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

تتيح لك القوائم البريدية تنظيم المشتركين في مجموعات لاستهداف الحملات. ينتمي كل سجل مشترك إلى قائمة واحدة، لكن يمكن لنفس عنوان البريد الإلكتروني أن يمتلك سجلات منفصلة في عدة قوائم، ويمكن للحملات استهداف قائمة بعينها أو شريحة محددة داخلها.

إنشاء قائمة

POST https://api.mail.land/v1/marketing/lists

Create list request

{
  "name": "Product Updates",
  "description": "Subscribers interested in product announcements"
}

الحقل	النوع	مطلوب	الوصف
`name`	string	نعم	اسم القائمة (يجب أن يكون فريداً لكل مساحة عمل)
`description`	string	لا	وصف القائمة

Create a mailing list

curl -X POST https://api.mail.land/v1/marketing/lists \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Product Updates", "description": "Product announcements" }'

الاستجابة

List response

{
  "id": "vtmlew96u277jq",
  "name": "Product Updates",
  "description": "Product announcements",
  "isActive": true,
  "subscriberCount": 0,
  "createdAt": "2026-02-17T12:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

عرض جميع القوائم البريدية

GET https://api.mail.land/v1/marketing/lists

المعامل	النوع	الافتراضي	الوصف
`cursor`	string	-	مؤشر معتم من `nextCursor` للصفحة السابقة. احذفه للصفحة الأولى.
`limit`	int	20	العناصر لكل صفحة
`search`	string	-	البحث بالاسم
`isActive`	bool	-	التصفية حسب الحالة النشطة
`sortBy`	string	-	حقل الفرز
`sortDesc`	bool	false	فرز تنازلي

List all mailing lists

curl "https://api.mail.land/v1/marketing/lists?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

List response

{
  "items": [
    {
      "id": "vtmlew96u277jq",
      "name": "Product Updates",
      "description": "Product announcements",
      "isActive": true,
      "subscriberCount": 2500,
      "createdAt": "2026-01-10T08:00:00Z",
      "updatedAt": "2026-02-17T12:00:00Z"
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

الحصول على تفاصيل القائمة

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

يُرجع تفاصيل موسّعة تشمل تفصيل المشتركين:

Get list details

curl https://api.mail.land/v1/marketing/lists/vtmlew96u277jq \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

List detail response

{
  "id": "vtmlew96u277jq",
  "name": "Product Updates",
  "description": "Product announcements",
  "isActive": true,
  "subscriberCount": 2500,
  "activeSubscribers": 2300,
  "unsubscribedCount": 150,
  "bouncedCount": 50,
  "createdAt": "2026-01-10T08:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

تحديث قائمة

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

Update list request

{
  "name": "Product Announcements",
  "description": "Updated description",
  "isActive": true
}

الحقل	النوع	مطلوب	الوصف
`name`	string	نعم	اسم القائمة (يجب أن يكون فريداً)
`description`	string	لا	وصف القائمة
`isActive`	bool	لا	الحالة النشطة (الافتراضي: `true`)

isActive مجرد وسم: تعيينه إلى false لا يمنع الإرسال. لا شيء في كود الحملات أو العامل (worker) يقرأ هذا الحقل لمنع حملة من استهداف هذه القائمة.

Update a mailing list

curl -X PUT https://api.mail.land/v1/marketing/lists/vtmlew96u277jq \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Announcements",
    "description": "Updated description",
    "isActive": true
  }'

حذف قائمة

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

يحذف القائمة البريدية. لا يتم حذف المشتركين في هذه القائمة، لكن يُمسح mailingListId الخاص بهم (مفتاح خارجي بقاعدة SetNull). تُحفظ حالات إلغاء الاشتراك المرتبطة بالقائمة عند حذفها.

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

Delete a mailing list

curl -X DELETE https://api.mail.land/v1/marketing/lists/vtmlew96u277jq \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

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

الحالة	الكود	الوصف
`400`	`VALIDATION_FAILED`	الاسم مطلوب
`400`	`INVALID_REQUEST`	توجد قائمة بريدية بهذا الاسم مسبقاً
`403`	`FORBIDDEN`	صلاحيات غير كافية
`404`	`RESOURCE_NOT_FOUND`	القائمة البريدية غير موجودة

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

المشتركون: أضف مشتركين إلى قوائمك
الشرائح: أنشئ شرائح ديناميكية داخل القوائم
الحملات: أرسل حملات إلى قوائمك

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

إنشاء قائمةنسخ رابط القسم

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

عرض جميع القوائم البريديةنسخ رابط القسم

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

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

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

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

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

في هذه الصفحة