MailLandDocs
التسويق

الحملات

إنشاء حملات التسويق عبر البريد الإلكتروني وجدولتها وإرسالها مع التتبع والتحليلات

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

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

تمر كل حملة بتدفق حالة محدد:

الحالةالقيمةالوصف
Draft0الحالة الأولية: قابلة للتعديل، لم تُرسَل بعد
Scheduled1في قائمة الانتظار للتسليم المستقبلي
Sending2قيد الإرسال إلى المستلمين
Sent3تمت معالجة جميع المستلمين
Paused4الإرسال متوقف في المنتصف
Cancelled5تم إلغاء الإرسال
Failed6خطأ في النظام أثناء الإرسال

الانتقالات المسموح بها:

  • Draft → Scheduled (جدولة) أو Sending (إرسال فوري) أو Cancelled (إلغاء)
  • Scheduled → Sending أو Cancelled: إعادة جدولة حملة في حالة Scheduled غير مدعومة
  • Sending → Sent أو Paused أو Cancelled أو Failed
  • Paused → Sending (استئناف)
  • Sent أو Cancelled → مؤرشف

أنواع الحملات

النوعالقيمةالوصف
Regular0حملة قياسية لمرة واحدة
Automated1يُفعَّل عبر الأتمتة
ABTest2حملة اختبار A/B

التخصيص (Personalization)

تدعم سطور الموضوع ومحتوى الحملة وسوم الدمج {{variable}}، التي تُستبدل لكل مستلم من سجل ذلك المشترك نفسه.

الوسمالقيمة
{{firstName}}الاسم الأول للمشترك
{{lastName}}اسم عائلة المشترك
{{fullName}}الاسم الأول والأخير مجتمعين
{{email}}عنوان البريد الإلكتروني للمشترك
{{subscriberId}}معرّف غامق للمشترك
{{custom_<field>}}أي حقل مخصص في المشترك، متاح أيضاً كـ {{<field>}}
محتوى حملة مخصص
<p>Hi {{firstName}}, here's what's new this month.</p>

الوسم الذي لا قيمة له يُترك كما كُتب تماماً: {{firstName}} لمشترك بلا اسم أول يبقى {{firstName}} في البريد المُسلَّم بدلاً من أن يصبح فراغاً. اكتب محتوى يُقرأ بشكل صحيح في الحالتين، مثلاً Hi there{{firstName}} خيار سيئ لكن "Your account" آمن. استخدم تحية بديلة عندما لا تكون متأكداً أن كل مشترك لديه الحقل.

تُهرَّب القيم بحسب الجزء الذي تحل فيه: محتوى HTML يُهرَّب كـ HTML (بحيث لا يمكن لاسم يحتوي على & أو < كسر تنسيقك)، بينما سطر الموضوع والنص العادي لا يُهرَّبان أبداً، تبقى Ben & Jerry's كما هي تماماً.

التهجئات القديمة بصيغة snake_case ({{first_name}}، {{last_name}}، {{full_name}}، {{subscriber_id}}) تستمر بالعمل كأسماء بديلة.

إنشاء حملة

يجب أن تكون مساحة العمل موثّقة كأعمال (Business Verified) قبل إنشاء أو تحديث أي حملة: وهو تحقق سابق ومنفصل عن تحقق fromEmail أدناه. إذا لم يكن كذلك، يُرفض الطلب بالخطأ 400 INVALID_REQUEST ("Marketing campaigns require Business Verified status…").

يجب أن يكون نطاق fromEmail مضافاً بالفعل ومُتحقَّقاً منه بالكامل (SPF + DKIM + DMARC) وقت الإنشاء والتحديث، وإلا يُرفض الطلب (400/404). يحدث هذا التحقق هنا، وليس وقت الإرسال، راجع الإرسال الفوري.

POST https://api.mail.land/v1/marketing/campaigns
Create campaign request
{
  "name": "February Newsletter",
  "subject": "What's new in February",
  "previewText": "Product updates and tips",
  "fromName": "MailLand Team",
  "fromEmail": "[email protected]",
  "replyTo": "[email protected]",
  "htmlContent": "<html>...</html>",
  "textContent": "Plain text version...",
  "type": 0,
  "mailingListId": "ddv6ou6kz4wbto",
  "segmentId": "x4xa3ep1zmqq0b"
}
الحقلالنوعمطلوبالوصف
namestringنعماسم الحملة
subjectstringنعمسطر موضوع البريد الإلكتروني
previewTextstringلانص المعاينة الظاهر في صندوق الوارد
fromNamestringنعمالاسم المعروض للمرسل
fromEmailstringنعمعنوان البريد الإلكتروني للمرسل
replyTostringلاعنوان الرد
htmlContentstringنعممحتوى HTML للبريد الإلكتروني
textContentstringلاالنسخة البديلة بالنص العادي
templateIdstringلامعرّف القالب للاستخدام
typeintلانوع الحملة (الافتراضي: 0 عادية)
mailingListIdstringلا*قائمة المراسلة المستهدفة
segmentIdstringلا*الشريحة المستهدفة

* أرسل mailingListId أو segmentId: أحدهما مطلوب ما لم يكن templateId محدداً.

Create a campaign
curl -X POST https://api.mail.land/v1/marketing/campaigns \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "February Newsletter",
    "subject": "What'\''s new in February",
    "fromName": "MailLand Team",
    "fromEmail": "[email protected]",
    "htmlContent": "<html><body><h1>Hello!</h1></body></html>",
    "mailingListId": "ddv6ou6kz4wbto"
  }'

الاستجابة

Campaign response
{
  "id": "uivozyvucowj9w",
  "name": "February Newsletter",
  "subject": "What's new in February",
  "previewText": "Product updates and tips",
  "fromName": "MailLand Team",
  "fromEmail": "[email protected]",
  "status": "draft",
  "statusName": "Draft",
  "type": 0,
  "typeName": "Regular",
  "mailingListId": "ddv6ou6kz4wbto",
  "mailingListName": "Main Newsletter",
  "segmentId": null,
  "segmentName": null,
  "createdAt": "2026-02-17T12:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

عرض قائمة الحملات

GET https://api.mail.land/v1/marketing/campaigns
المعاملالنوعالافتراضيالوصف
cursorstring-مؤشر معتم من nextCursor للصفحة السابقة. احذفه للصفحة الأولى.
limitint20العناصر لكل صفحة (الحد الأقصى 100)
searchstring-البحث بالاسم
statusint-التصفية بـ CampaignStatus
typeint-التصفية بـ CampaignType
mailingListIdstring-التصفية بقائمة المراسلة
sortBystring-حقل الفرز
sortDescboolfalseالفرز تنازلياً
includeArchivedboolfalseتضمين الحملات المؤرشفة
List campaigns
curl "https://api.mail.land/v1/marketing/campaigns?limit=20&status=3" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Campaign list response
{
  "items": [
    {
      "id": "uivozyvucowj9w",
      "name": "February Newsletter",
      "subject": "What's new in February",
      "status": "sent",
      "statusName": "Sent",
      "type": 0,
      "typeName": "Regular",
      "mailingListId": "ddv6ou6kz4wbto",
      "mailingListName": "Main Newsletter",
      "totalRecipients": 5000,
      "totalSent": 4980,
      "totalDelivered": 4900,
      "totalOpened": 1520,
      "totalClicked": 195,
      "totalBounced": 45,
      "totalUnsubscribed": 12,
      "sentAt": "2026-02-15T10:00:00Z",
      "completedAt": "2026-02-15T10:35:00Z",
      "createdAt": "2026-02-14T08:00:00Z"
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

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

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

يُعيد CampaignDetailDto الكامل بما يشمل محتوى HTML وجميع الإحصائيات ومعدلات التفاعل المحسوبة:

Get campaign details
curl https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Campaign detail response
{
  "id": "uivozyvucowj9w",
  "name": "February Newsletter",
  "subject": "What's new in February",
  "previewText": "Product updates and tips",
  "fromName": "MailLand Team",
  "fromEmail": "[email protected]",
  "replyTo": "[email protected]",
  "status": "sent",
  "statusName": "Sent",
  "type": 0,
  "typeName": "Regular",
  "htmlContent": "<html>...</html>",
  "textContent": "Plain text...",
  "mailingListId": "ddv6ou6kz4wbto",
  "mailingListName": "Main Newsletter",
  "totalRecipients": 5000,
  "totalSent": 4980,
  "totalDelivered": 4900,
  "totalOpened": 1520,
  "totalClicked": 195,
  "totalBounced": 45,
  "totalUnsubscribed": 12,
  "totalComplaints": 2,
  "deliveryRate": 98.39,
  "openRate": 31.02,
  "clickRate": 3.98,
  "clickToOpenRate": 12.83,
  "bounceRate": 0.9,
  "unsubscribeRate": 0.24,
  "openTrackingEnabled": true,
  "clickTrackingEnabled": true,
  "sentAt": "2026-02-15T10:00:00Z",
  "completedAt": "2026-02-15T10:35:00Z",
  "createdAt": "2026-02-14T08:00:00Z",
  "updatedAt": "2026-02-15T10:35:00Z"
}

معدلات التفاعل

المعدلالصيغة
deliveryRatetotalDelivered / totalSent * 100
openRatetotalOpened / totalDelivered * 100
clickRatetotalClicked / totalDelivered * 100
clickToOpenRatetotalClicked / totalOpened * 100
bounceRatetotalBounced / totalSent * 100
unsubscribeRatetotalUnsubscribed / totalDelivered * 100

تُحسب المعدلات على الخادم من العدّادات الخام (الفتحات والنقرات فريدة لكل مستلم). deliveryRate وbounceRate نسبتان إلى المُرسَل؛ وopenRate وclickRate وunsubscribeRate نِسَب إلى المُسلَّم؛ أما clickToOpenRate (CTOR) فهو النقرات نسبةً إلى الفتحات ومقياس مستقل عن clickRate. المعدل نسبة مئوية بلا سقف (قد يتجاوز clickToOpenRate 100) وقيمته null لا 0 عند عدم توفره: المقام صفر أو أن التتبع المطلوب متوقف في الحساب (openTrackingEnabled / clickTrackingEnabled تُظهران الإعداد الحالي). لدمج الحملات اجمع العدّادات واقسم مرة واحدة؛ لا تأخذ متوسط النسب. وتُرجع القائمة الحقول نفسها لكل حملة.

تحديث حملة

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

يمكن تحديث الحملات ذات الحالة Draft أو Scheduled فقط. يتطابق نص الطلب مع طلب الإنشاء، باستثناء type الذي لا يمكن تغييره.

الحالةالكودالوصف
200-تم تحديث الحملة
400INVALID_REQUESTيمكن تعديل الحملات المسودة فقط
404RESOURCE_NOT_FOUNDالحملة غير موجودة
Update a campaign
curl -X PUT https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "February Newsletter (Updated)",
    "subject": "What'\''s new in February - updated",
    "fromName": "MailLand Team",
    "fromEmail": "[email protected]",
    "htmlContent": "<html><body><h1>Updated!</h1></body></html>",
    "mailingListId": "ddv6ou6kz4wbto"
  }'

جدولة حملة

POST https://api.mail.land/v1/marketing/campaigns/{id}/schedule
Schedule request
{
  "scheduledAt": "2026-02-20T14:00:00Z"
}

يجب أن يكون وقت scheduledAt في المستقبل. تتغير حالة الحملة إلى Scheduled ويلتقطها CampaignWorker في الوقت المحدد.

الجدولة مسموحة فقط من حالة Draft: لا يمكن إعادة جدولة حملة في حالة Scheduled بالفعل عبر هذه النقطة.

الحالةالكودالوصف
200-تمت جدولة الحملة
400VALIDATION_FAILEDيجب أن يكون وقت الجدولة في المستقبل
404RESOURCE_NOT_FOUNDالحملة غير موجودة أو لا يمكن جدولتها
403MARKETING_NOT_YET_ALLOWEDالتسويق غير مفتوح للحساب بعد (راجع رموز الأخطاء)؛ ويعيده /send أيضًا
403MARKETING_SUSPENDEDالتسويق غير متاح على مستوى المنصة؛ ويعيده /send أيضًا
422CAMPAIGN_LINK_BLOCKEDرابط في الحملة يشير إلى وجهة مصنّفة على أنها غير آمنة؛ ويعيده /send أيضًا. لا تتم جدولة أو إرسال أي شيء
Schedule a campaign
curl -X POST https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w/schedule \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "scheduledAt": "2026-02-20T14:00:00Z" }'

الإرسال الفوري

POST https://api.mail.land/v1/marketing/campaigns/{id}/send

يُرسل الحملة فوراً. تنتقل حالة الحملة إلى Sending، ويبدأ CampaignWorker في معالجة المستلمين.

لا يتحقق /send نفسه من حالة تحقق النطاق: يحدث هذا الفحص وقت الإنشاء/التحديث (راجع إنشاء حملة). يُعيد /send الرمز 422 CAMPAIGN_NO_ELIGIBLE_RECIPIENTS إذا لم يكن أي أحد في القائمة/الشريحة المستهدفة مؤهلاً لاستلام الحملة (مثلاً إذا كان الجميع مكبوتين أو أوقفوا الاشتراك).

Send a campaign immediately
curl -X POST https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w/send \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

الإيقاف المؤقت والاستئناف

إيقاف حملة قيد الإرسال مؤقتاً:

POST https://api.mail.land/v1/marketing/campaigns/{id}/pause
Pause a campaign
curl -X POST https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w/pause \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

استئناف حملة متوقفة:

POST https://api.mail.land/v1/marketing/campaigns/{id}/resume
Resume a campaign
curl -X POST https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w/resume \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

يوقف الإيقاف المؤقت CampaignWorker عن معالجة المستلمين المتبقين. لا تتأثر رسائل البريد الإلكتروني المُرسَلة مسبقاً. يستأنف الإرسال من حيث توقف.

إلغاء حملة

POST https://api.mail.land/v1/marketing/campaigns/{id}/cancel

يُلغي حملة Draft أو Scheduled أو Sending. لا يتم استرداد رسائل البريد الإلكتروني المُرسَلة مسبقاً.

Cancel a campaign
curl -X POST https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w/cancel \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

نسخ حملة

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

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

Duplicate a campaign
curl -X POST "https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w/duplicate?name=Copy%20of%20Newsletter" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

الأرشفة وإلغاء الأرشفة

أرشفة حملة Sent أو Cancelled:

POST https://api.mail.land/v1/marketing/campaigns/{id}/archive
Archive a campaign
curl -X POST https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w/archive \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

إلغاء أرشفة حملة مؤرشفة:

POST https://api.mail.land/v1/marketing/campaigns/{id}/unarchive
Unarchive a campaign
curl -X POST https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w/unarchive \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

تُخفى الحملات المؤرشفة من عرض القائمة الافتراضي ما لم يتم تمرير includeArchived=true.

مستلمو الحملة

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

GET https://api.mail.land/v1/marketing/campaigns/{id}/recipients
المعاملالنوعالافتراضيالوصف
cursorstring-مؤشر معتم من nextCursor للصفحة السابقة. احذفه للصفحة الأولى.
limitint20العناصر لكل صفحة (الحد الأقصى 100)
statusstring-التصفية بحالة المستلم
searchstring-البحث بالبريد الإلكتروني
Get campaign recipients
curl "https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w/recipients?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Campaign recipients response
{
  "items": [
    {
      "email": "[email protected]",
      "status": "Opened",
      "sentAt": "2026-02-15T10:00:30Z",
      "deliveredAt": "2026-02-15T10:00:32Z",
      "openedAt": "2026-02-15T11:15:00Z",
      "clickedAt": "2026-02-15T11:16:30Z",
      "bouncedAt": null,
      "complainedAt": null,
      "unsubscribedAt": null,
      "openCount": 2,
      "clickCount": 1,
      "bounceReason": null
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

حالات المستلمين

الحالةالقيمةالوصف
Pending0في قائمة الانتظار، لم يُرسَل بعد
Sent1قُبل من قبل MTA
Delivered2تم تسليمه إلى المستلم
Opened3فتحه المستلم
Clicked4نقر المستلم على رابط
Bounced5ارتداد صعب
Unsubscribed6ألغى المستلم الاشتراك
Complained7شكوى بريد مزعج
Failed8فشل التسليم

تتضمن openedAt/openCount وclickedAt/clickCount نشاطاً آلياً، الجلب المسبق لحماية خصوصية بريد Apple وماسحات الروابط الأمنية، والتي لا تُصفّيها MailLand حالياً. عامل المعدلات المشتقة من الفتح/النقر كحد أعلى، وليس رقماً دقيقاً لتفاعل بشري.

حذف حملة

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

يحذف الحملة وبيانات مستلميها بشكل دائم. يمكن حذف الحملات في حالة Draft أو Scheduled فقط؛ حذف أي حالة أخرى يُعيد 404: استخدم الأرشفة بدلاً من ذلك للحملات المُرسَلة.

Delete a campaign
curl -X DELETE https://api.mail.land/v1/marketing/campaigns/uivozyvucowj9w \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

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

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

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

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

تسخين IP

زيادة حجم الإرسال تدريجيًا على النطاقات الجديدة لبناء سمعة المرسل

المشتركون

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

في هذه الصفحة

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