المشتركون

إدارة جهات اتصال المشتركين واستيراد القوائم وتتبع التفاعل

إدارة جهات اتصال المشتركين في البريد الإلكتروني. يمتلك كل مشترك ملفاً شخصياً يتضمن تتبع التفاعل والحقول المخصصة وإدارة الحالة.

حالات المشترك

الحالة	القيمة	الوصف
`Active`	0	مشترك ويتلقى رسائل البريد الإلكتروني
`Unsubscribed`	1	أوقف اشتراكه في رسائل البريد الإلكتروني
`Bounced`	2	تم تسجيل ارتداد صريح
`Complained`	3	قدّم شكوى بريد عشوائي
`Pending`	4	محجوز: لا يوجد تدفق تأكيد مزدوج (double opt-in) في MailLand، لذا لا شيء يضبط هذه الحالة أبداً

optInMethod وحقول consent* على المشترك تُسجَّل كدليل فقط، ولا تُشغِّل أي سير عمل للتأكيد.

إنشاء مشترك

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

Create subscriber request

{
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1234567890",
  "company": "Acme Corp",
  "mailingListId": "ddv6ou6kz4wbto",
  "source": "api",
  "birthday": "1990-05-14",
  "customFields": {
    "plan": "enterprise",
    "region": "us-west"
  }
}

الحقل	النوع	مطلوب	الوصف
`email`	string	نعم	عنوان البريد الإلكتروني
`firstName`	string	لا	الاسم الأول
`lastName`	string	لا	اسم العائلة
`phone`	string	لا	رقم الهاتف
`company`	string	لا	اسم الشركة
`mailingListId`	string	لا	القائمة البريدية للإضافة إليها
`source`	string	لا	مصدر الاشتراك (مثل `api` أو `form` أو `import`)
`birthday`	string	لا	`YYYY-MM-DD`. يقرأه مُحفِّز أتمتة `DateBased`
`customFields`	object	لا	حقول مخصصة بصيغة مفتاح-قيمة

Create a subscriber

curl -X POST https://api.mail.land/v1/marketing/subscribers \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "mailingListId": "ddv6ou6kz4wbto",
    "source": "api"
  }'

الاستجابة

Subscriber response

{
  "id": "exz31qoqlf01sj",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1234567890",
  "company": "Acme Corp",
  "status": "active",
  "statusName": "Active",
  "source": "api",
  "mailingListId": "ddv6ou6kz4wbto",
  "mailingListName": "Product Updates",
  "customFields": {
    "plan": "enterprise",
    "region": "us-west"
  },
  "subscribedAt": "2026-02-17T12:00:00Z",
  "unsubscribedAt": null,
  "createdAt": "2026-02-17T12:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

قائمة المشتركين

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

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

List subscribers

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

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

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

يُرجع ملفاً شخصياً موسعاً يتضمن مقاييس التفاعل:

Get subscriber details

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

Subscriber detail response

{
  "id": "exz31qoqlf01sj",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1234567890",
  "company": "Acme Corp",
  "status": "active",
  "source": "api",
  "mailingListId": "ddv6ou6kz4wbto",
  "mailingListName": "Product Updates",
  "customFields": { "plan": "enterprise" },
  "birthday": "1990-05-14",
  "emailsSent": 50,
  "emailsOpened": 25,
  "emailsClicked": 10,
  "lastEmailSentAt": "2026-02-17T09:30:00Z",
  "lastEmailOpenedAt": "2026-02-16T15:20:00Z",
  "lastEmailClickedAt": "2026-02-15T11:10:00Z",
  "openRate": 50.0,
  "clickRate": 40.0,
  "subscribedAt": "2026-01-15T08:00:00Z",
  "createdAt": "2026-01-15T08:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

تحديث مشترك

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

Update subscriber request

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phone": "+1234567890",
  "company": "TechCorp",
  "mailingListId": "ddv6ou6kz4wbto",
  "customFields": { "plan": "pro" },
  "birthday": "1990-05-14",
  "status": "Active"
}

عملية PUT تستبدل الملف الشخصي بالكامل، ولا تدمجه. يتم استبدال firstName وlastName وphone وcompany وmailingListId كلها بـ null (أو إزالة من القائمة) عند حذفها، وليس تركها كما هي. حذف mailingListId يزيل عضوية المشترك في القائمة. أرسل كل حقل تريد الاحتفاظ به، بما في ذلك mailingListId. فقط customFields وstatus تبقى دون تغيير عند حذفها. أما birthday فيتبع قاعدته الخاصة: حذف الحقل يتركه دون تغيير، وإرسال "birthday": null يمسحه، وإرسال قيمة YYYY-MM-DD يضبطه، وسلسلة فارغة ("") تُرفض بـ 400. إذا كان لدى المستلم بالفعل جهة اتصال ليست في أي قائمة، تُحفظ العضوية التي أزلتها كسجل تاريخي فقط: لا تظهر بعد الآن ضمن جهات الاتصال، وتُحفظ إلغاءات الاشتراك وسجلات الموافقة وسجل الحملات.

Update a subscriber

curl -X PUT https://api.mail.land/v1/marketing/subscribers/exz31qoqlf01sj \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "company": "TechCorp",
    "mailingListId": "ddv6ou6kz4wbto",
    "customFields": { "plan": "pro" },
    "status": "Active"
  }'

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

POST https://api.mail.land/v1/marketing/subscribers/{id}/unsubscribe

يسجل إلغاء اشتراك مقتصر على قائمة المشترك، أو على جميع الإرسالات التسويقية إذا لم يكن للمشترك قائمة، ويحدّث حالة المشترك إلى Unsubscribed مع طابع زمني unsubscribedAt. لا يتأثر البريد المعاملاتي بهذا الاستدعاء.

Unsubscribe a subscriber

curl -X POST https://api.mail.land/v1/marketing/subscribers/exz31qoqlf01sj/unsubscribe \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

حذف مشترك

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

يحذف المشترك وبيانات تفاعله نهائياً. تُحفظ حالات إلغاء الاشتراك والكبح، بحيث لا تؤدي إعادة إضافة نفس العنوان إلى إعادة اشتراكه.

Delete a subscriber

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

استيراد المشتركين

POST https://api.mail.land/v1/marketing/subscribers/import

استيراد المشتركين من محتوى CSV:

Import request

{
  "mailingListId": "ddv6ou6kz4wbto",
  "csvContent": "email,firstName,lastName\n[email protected],John,Doe\n[email protected],Jane,Smith",
  "source": "csv_import",
  "updateExisting": true
}

الحقل	النوع	مطلوب	الوصف
`mailingListId`	string	لا	القائمة البريدية الهدف
`csvContent`	string	نعم	بيانات CSV: راجع تنبيه التنسيق أدناه، صف الترويسة لا يُستخدم كترويسة

يُعامَل الصف الأول كترويسة ويُتجاهل، بغض النظر عن محتواه: لا يُقرأ أبداً لربط الأعمدة 1–3 بالحقول. الأعمدة موضعية: العمود 1 دائماً email، العمود 2 دائماً firstName، العمود 3 دائماً lastName؛ أي عمود آخر يُتجاهل باستثناء عمود عنوانه birthday (بغض النظر عن حالة الأحرف، في أي موضع بعد العمود 1)، ويُقرأ حسب اسم عنوانه لا حسب موضعه. يجب أن تكون قيمته بصيغة YYYY-MM-DD؛ وتُبلَّغ القيمة غير الصالحة لكل صف في errors وتظل جهة الاتصال تلك مستوردة، لكن دون تاريخ ميلاد. أي ملف بلا عنوان birthday يتصرف تماماً كما كان سابقاً. تُقسَّم القيم على الفواصل العادية، لذا فإن قيمة تحتوي على فاصلة داخل علامتي اقتباس غير مدعومة وستُقسَّم بشكل خاطئ. تضيف الاستجابة أيضاً عدادات importedNewMembershipForExistingRecipient وupdatedMembership وalreadyMember وsuppressed وskippedDuplicateInFile بالإضافة إلى ما هو موضح أدناه.

Import subscribers

curl -X POST https://api.mail.land/v1/marketing/subscribers/import \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "mailingListId": "ddv6ou6kz4wbto",
    "csvContent": "email,firstName,lastName\[email protected],John,Doe\[email protected],Jane,Smith",
    "source": "csv_import",
    "updateExisting": true
  }'

Import response

{
  "imported": 50,
  "updated": 10,
  "skipped": 5,
  "errors": [
    "Invalid email: not-an-email",
    "Could not resolve a recipient identity for: [email protected]"
  ]
}

المشتركون الذين يُستوردون يُشغِّلون أتمتة SubscriberJoins، لكل عضوية يُنشئها الاستيراد فعلياً: بنفس طريقة الإنشاء الفردي عبر POST /v1/marketing/subscribers. جهة اتصال موجودة بالفعل في القائمة المستهدفة، أو تكرار داخل الملف، أو صف فُقد بسبب تعارض (TenantId, Email) لا يُسجَّل. إذا كانت القائمة المستهدفة تملك أتمتة SubscriberJoins نشطة (أو كان لدى المستأجر واحدة غير مرتبطة بقائمة معينة)، فإن استيراد ملف يحتوي جهات اتصال جديدة يُرسل الآن تلك الأتمتة إلى كل واحدة منها، قدِّر حجم الاستيراد وفقاً لذلك. لا يزال الحظر (suppression) مُطبَّقاً: التسجيل لا يتجاوز أبداً مستلماً محظوراً.

تصدير المشتركين

GET https://api.mail.land/v1/marketing/subscribers/export

المعامل	النوع	الوصف
`mailingListId`	string	التصفية حسب القائمة البريدية
`status`	int	التصفية حسب الحالة

يُرجع ملف CSV للتنزيل باسم subscribers_yyyyMMdd_HHmmss.csv.

Export subscribers

curl "https://api.mail.land/v1/marketing/subscribers/export?mailingListId=ddv6ou6kz4wbto" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -o subscribers_export.csv

إحصائيات المشتركين

GET https://api.mail.land/v1/marketing/subscribers/stats

المعامل	النوع	الوصف
`mailingListId`	string	التصفية حسب القائمة البريدية

Get subscriber stats

curl "https://api.mail.land/v1/marketing/subscribers/stats?mailingListId=ddv6ou6kz4wbto" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Subscriber stats response

{
  "total": 1500,
  "active": 1200,
  "unsubscribed": 200,
  "bounced": 80,
  "complained": 10,
  "pending": 10
}

عدد المشتركين

GET https://api.mail.land/v1/marketing/subscribers/count

المعامل	النوع	الوصف
`mailingListId`	string	التصفية حسب القائمة البريدية

Get subscriber count

curl "https://api.mail.land/v1/marketing/subscribers/count?mailingListId=ddv6ou6kz4wbto" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Count response

{
  "count": 1500,
  "mailingListId": "ddv6ou6kz4wbto"
}

نمو المشتركين

GET https://api.mail.land/v1/marketing/subscribers/growth

المعامل	النوع	الافتراضي	الوصف
`days`	int	30	فترة الرجوع إلى الوراء (الحد الأقصى 90)
`mailingListId`	string	-	التصفية حسب القائمة البريدية

Get subscriber growth

curl "https://api.mail.land/v1/marketing/subscribers/growth?days=30&mailingListId=ddv6ou6kz4wbto" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Growth response

{
  "dataPoints": [
    {
      "date": "2026-02-17",
      "newSubscribers": 50,
      "unsubscribes": 5,
      "cumulativeTotal": 1500
    }
  ],
  "totalNew": 500,
  "totalUnsubscribes": 50,
  "netGrowth": 450,
  "currentTotal": 1500
}

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

الحالة	الكود	الوصف
`400`	`INVALID_EMAIL_FORMAT`	تنسيق البريد الإلكتروني غير صالح
`400`	`INVALID_REQUEST`	عنوان البريد الإلكتروني للمشترك موجود مسبقاً
`403`	`FORBIDDEN`	صلاحيات غير كافية
`404`	`RESOURCE_NOT_FOUND`	المشترك غير موجود

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

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

المشتركون

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

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

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

قائمة المشتركيننسخ رابط القسم

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

تحديث مشتركنسخ رابط القسم

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

حذف مشتركنسخ رابط القسم

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

تصدير المشتركيننسخ رابط القسم

إحصائيات المشتركيننسخ رابط القسم

عدد المشتركيننسخ رابط القسم

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

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

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

في هذه الصفحة