MailLandDocs
التسويق

الأتمتة

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

تتيح لك الأتمتة إنشاء تسلسلات بريد إلكتروني متعددة الخطوات تُفعَّل بأحداث المشتركين. حدّد محفزاً، وابنِ تسلسلاً من الخطوات، وسيقوم MailLand بتنفيذ التدفق تلقائياً عند إطلاق المحفز.

محفزات الأتمتة

تبدأ كل أتمتة بمحفز واحد:

المحفزالقيمةالوصف
SubscriberJoins0تتم إضافة مشترك إلى قائمة بريدية
SubscriberUpdated1يتم تحديث ملف المشترك التعريفي
CampaignOpened2يفتح المشترك حملة محددة
CampaignClicked3ينقر المشترك على رابط في حملة
DateBased4محفز مبني على عيد الميلاد فقط، يُقيّم Subscriber.Birthday (راجع التنبيه أدناه)

لا يُقيّم DateBased سوى Subscriber.Birthday، وليس أي حقل تاريخ متكرر عشوائي. يمكن ضبط Birthday عبر POST/PUT /v1/marketing/subscribers (راجع صفحة المشتركين) وكذلك عبر استيراد CSV الذي يقبل عمود birthday اختيارياً، لذا تُسجّل أتمتة DateBased أي مشترك تم ضبط تاريخ ميلاده بأي من الطريقتين.

| Manual | 5 | يُفعَّل يدوياً عبر API |

حالات الأتمتة

الحالةالقيمةالوصف
Draft0قابلة للتعديل، غير مُشغَّلة
Active1مُشغَّلة: يتم تسجيل المشتركين الجدد عند إطلاق المحفز
Paused2متوقفة مؤقتاً: لا تسجيلات جديدة، وتتوقف الخطوات اللاحقة للمشتركين المسجَّلين بالفعل. إعادة التفعيل (Active) تستأنف كل تسجيل من حيث توقف تماماً، وتُسلّم كل ما استحق أثناء التوقف
Archived3مؤرشفة: مخفية من العروض الافتراضية. مثل Paused، هذا يوقف التسجيلات الجديدة؛ كما تتوقف الخطوات اللاحقة للمشتركين المسجَّلين بالفعل. لا توجد نقطة نهاية لإلغاء الأرشفة، لذا هذا التوقف دائم لهذه التسجيلات

أنواع الخطوات

تحتوي كل أتمتة على تسلسل مرتب من الخطوات:

نوع الخطوةالقيمةالوصف
SendEmail0إرسال بريد إلكتروني إلى المشترك
Wait1الانتظار لمدة محددة قبل المتابعة
Condition2يُقيّم حقلاً من حقول المشترك؛ بوابة تستمر عند الصحة وتُنهي التسجيل عند الخطأ (راجع خطوة Condition أدناه)
AddToList3إضافة المشترك إلى قائمة بريدية
RemoveFromList4إزالة المشترك من قائمة بريدية
UpdateSubscriber5تحديث حقول المشترك
Webhook6إرسال webhook إلى عنوان URL خارجي

التخصيص (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}}) تستمر بالعمل كأسماء بديلة.

إنشاء أتمتة

POST https://api.mail.land/v1/marketing/automations
طلب إنشاء أتمتة
{
  "name": "Welcome Series",
  "description": "3-email welcome sequence for new subscribers",
  "trigger": 0,
  "mailingListId": "7h3n5k8w2q9m1t",
  "campaignId": null,
  "steps": [
    {
      "type": 0,
      "order": 1,
      "templateId": "2p9x4k7m3q8n1z",
      "subject": "Welcome to our newsletter!"
    },
    {
      "type": 1,
      "order": 2,
      "delayMinutes": 1440
    },
    {
      "type": 0,
      "order": 3,
      "templateId": "9k4p2x7m1q3n8z"
    }
  ]
}
الحقلالنوعمطلوبالوصف
namestringنعماسم الأتمتة (فريد في مساحة العمل)
descriptionstringلاوصف الأتمتة
triggerintنعمنوع المحفز (انظر جدول المحفزات)
mailingListIdstringلاالقائمة البريدية المستهدفة للمحفز
campaignIdstringلااختياري لمحفزات CampaignOpened / CampaignClicked: عند حذفه، يُطلق المحفز عند فتح أي حملة، وليس حملة واحدة فقط
stepsarrayنعمتسلسل مرتب من الخطوات

لا يوجد حقل segmentId في الأتمتة: هذا الحقل غير موجود هنا (تُستخدم الشرائح في مكان آخر، مثل الحملات). يأتي محتوى خطوة SendEmail من templateId، وليس من htmlContent/textContent/fromName/fromEmail المضمّنة.

campaignId اختياري لمحفزات الفتح/النقر، وليس مطلوباً كما ذكرت نسخ سابقة من هذه الصفحة. كما يُطلق أيضاً عند فتحات آلية (الجلب المسبق لحماية خصوصية بريد Apple، وماسحات روابط الأمان) التي لا يُصفّيها MailLand اليوم.

حقول الخطوات

شكل كل خطوة فعلياً هو { order, type, delayMinutes, templateId, subject, settings: {} }: لا يوجد segmentId على مستوى الأتمتة، ولا تملك الخطوات الحقول الخاصة بكل نوع الموضحة في نسخ سابقة من هذه الصفحة (conditionField، targetMailingListId، updateField، webhookUrl، fromName، fromEmail، replyTo ليست حقولاً في المستوى الأعلى للخطوة). الجداول أدناه تعكس الشكل الحقيقي.

خطوة SendEmail (type: 0):

الحقلالنوعمطلوبالوصف
typeintنعم0
orderintنعمموضع الخطوة في التسلسل
delayMinutesintلاعدد الدقائق للانتظار قبل تنفيذ هذه الخطوة: حتى عندما تكون الخطوة الأولى: أصبح التأخير قبل أول إرسال يُحترم الآن عند التسجيل (كان يُتجاهل سابقاً)
templateIdstringنعمالقالب الذي يوفّر محتوى البريد الإلكتروني، يأتي المحتوى فقط من القالب
subjectstringلايستبدل موضوع القالب إذا تم تعيينه

لا يوجد htmlContent/textContent/fromName/fromEmail/replyTo مضمّن في خطوة. المرسل ثابت على noreply@<أول نطاق موثّق بالكامل>، ويُعرض مع اسم مساحة العمل، وغير قابل للتهيئة لكل خطوة.

templateId مطلوب في كل خطوة SendEmail. تُرفض طلبات الإنشاء/التحديث التي لا تحتوي عليه بـ 400 VALIDATION_FAILED؛ وtemplateId الذي لا يشير إلى قالب في مستأجرك يُرفض بـ 400 TEMPLATE_NOT_FOUND، كلاهما قبل كتابة أي شيء. إذا حُذف القالب بعد حفظ الأتمتة، يُوسم تسجيل أول مشترك يصل إلى تلك الخطوة بـ Failed بدلاً من تخطي الخطوة بصمت، ويُحتسب ضمن totalFailed الخاص بالأتمتة (راجع الحصول على تفاصيل الأتمتة).

خطوة Wait (type: 1):

الحقلالنوعمطلوبالوصف
typeintنعم1
orderintنعمموضع الخطوة
delayMinutesintنعمعدد الدقائق للانتظار قبل الخطوة التالية

خطوة Condition (type: 2):

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

الحقلالنوعمطلوبالوصف
typeintنعم2
orderintنعمموضع الخطوة
settings.conditionFieldstringنعمحقل المشترك المراد تقييمه: email، firstName، lastName، phone، company، source، أو custom_<name> لحقل مخصص
settings.conditionOperatorstringنعمequals، notEquals، contains، notContains، startsWith، endsWith، isEmpty، isNotEmpty (غير حساس لحالة الأحرف)
settings.conditionValuestringمطلوب إلا مع isEmpty/isNotEmptyالقيمة المراد مقارنتها

المقارنات هي مقارنات نصية غير حساسة لحالة الأحرف، بنفس المعاملات التي تقدّمها الشرائح (segments) بالفعل. تُعاد 400 VALIDATION_FAILED عند الإنشاء/التحديث عندما يكون conditionField غير معروف، أو conditionOperator ليس أحد القيم أعلاه، أو عندما يكون conditionValue مفقوداً لعامل يحتاج إلى قيمة.

خطوة Condition محفوظة قبل وجود هذا التحقق (وبالتالي إعداداتها غير قابلة للتقييم) تستمر في المرور دون تغيير، للحفاظ على الاستمرارية: فقط طلبات الإنشاء/التحديث الجديدة يتم التحقق منها.

خطوات AddToList / RemoveFromList (type: 3، 4):

الحقلالنوعمطلوبالوصف
typeintنعم3 أو 4
orderintنعمموضع الخطوة
settings.mailingListIdstringنعمالقائمة البريدية لإضافة/إزالة المشترك، تُقرأ من settings

خطوة UpdateSubscriber (type: 5):

الحقلالنوعمطلوبالوصف
typeintنعم5
orderintنعمموضع الخطوة
settingsobjectنعميُكتب كل مفتاح في settings كحقل مخصص على المشترك

خطوة Webhook (type: 6):

الحقلالنوعمطلوبالوصف
typeintنعم6
orderintنعمموضع الخطوة
settings.urlstringنعمعنوان URL لإرسال طلب POST إليه، يُقرأ من settings

تُوقَّع طلبات خطوة Webhook بسر خاص بمستقبِل الخطوة (X-MLND-Signature، ويُتحقق منه كما في ويب هوك العملاء): لكل عنوان URL مختلف لخطوة سر خاص به، فلا يستطيع أي مستقبِل التوقيع نيابةً عن آخر. اقرأ الأسرار عبر GET /v1/marketing/automations/{id}/webhook-signing-secrets وجدّدها عبر POST /v1/marketing/automations/{id}/webhook-signing-secrets/regenerate، راجع الإصدارات. أرسل { "webhookUrl": "…" } لتجديد سر مستقبِل واحد فقط.

Create an automation
curl -X POST https://api.mail.land/v1/marketing/automations \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Series",
    "trigger": 0,
    "mailingListId": "7h3n5k8w2q9m1t",
    "steps": [
      {
        "type": 0, "order": 1,
        "subject": "Welcome!",
        "templateId": "2p9x4k7m3q8n1z"
      },
      { "type": 1, "order": 2, "delayMinutes": 1440 },
      {
        "type": 0, "order": 3,
        "subject": "Getting started",
        "templateId": "9k4p2x7m1q3n8z"
      }
    ]
  }'

الاستجابة

استجابة الأتمتة
{
  "id": "4f8k2m9p1q6z3s",
  "name": "Welcome Series",
  "description": "3-email welcome sequence for new subscribers",
  "trigger": "subscriberJoins",
  "triggerName": "SubscriberJoins",
  "status": "draft",
  "statusName": "Draft",
  "mailingListId": "7h3n5k8w2q9m1t",
  "mailingListName": "Product Updates",
  "campaignId": null,
  "campaignName": null,
  "stepsCount": 3,
  "totalEnrolled": 0,
  "totalCompleted": 0,
  "activatedAt": null,
  "createdAt": "2026-02-17T12:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

لا يوجد حقل segmentId/segmentName في الأتمتة، وعدادات التسجيل هي totalEnrolled/totalCompleted (وليست totalEnrollments/activeEnrollments/completedEnrollments). تضيف استجابة التفاصيل أيضاً steps (قائمة الخطوات الكاملة)، وcompletionRate، وtotalFailed: التسجيلات التي وصلت إلى خطوة SendEmail بلا قالب في المستأجر (مفقود أو محذوف لاحقاً).

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

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

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

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

يُعيد الأتمتة الكاملة بما في ذلك جميع الخطوات:

Get automation details
curl https://api.mail.land/v1/marketing/automations/4f8k2m9p1q6z3s \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
استجابة تفاصيل الأتمتة
{
  "id": "4f8k2m9p1q6z3s",
  "name": "Welcome Series",
  "description": "3-email welcome sequence for new subscribers",
  "trigger": "subscriberJoins",
  "triggerName": "SubscriberJoins",
  "status": "active",
  "statusName": "Active",
  "mailingListId": "7h3n5k8w2q9m1t",
  "mailingListName": "Product Updates",
  "campaignId": null,
  "campaignName": null,
  "stepsCount": 3,
  "totalEnrolled": 230,
  "totalCompleted": 200,
  "totalFailed": 4,
  "activatedAt": "2026-01-10T08:05:00Z",
  "steps": [
    {
      "order": 1,
      "type": "sendEmail",
      "typeName": "SendEmail",
      "delayMinutes": null,
      "templateId": "2p9x4k7m3q8n1z",
      "subject": "Welcome to our newsletter!",
      "settings": null
    },
    {
      "order": 2,
      "type": "wait",
      "typeName": "Wait",
      "delayMinutes": 1440,
      "templateId": null,
      "subject": null,
      "settings": null
    },
    {
      "order": 3,
      "type": "sendEmail",
      "typeName": "SendEmail",
      "delayMinutes": null,
      "templateId": "9k4p2x7m1q3n8z",
      "subject": "Getting started with MailLand",
      "settings": null
    }
  ],
  "completionRate": 86.96,
  "createdAt": "2026-01-10T08:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

تحديث أتمتة

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

يمكن تحديث أي حالة باستثناء Active (وليس Draft/Paused فقط). يتطابق محتوى الطلب مع طلب الإنشاء.

Update an automation
curl -X PUT https://api.mail.land/v1/marketing/automations/4f8k2m9p1q6z3s \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Series",
    "trigger": 0,
    "mailingListId": "7h3n5k8w2q9m1t",
    "steps": [
      {
        "type": 0, "order": 1,
        "subject": "Welcome!",
        "templateId": "2p9x4k7m3q8n1z"
      },
      { "type": 1, "order": 2, "delayMinutes": 1440 },
      {
        "type": 0, "order": 3,
        "subject": "Getting started",
        "templateId": "9k4p2x7m1q3n8z"
      }
    ]
  }'

تفعيل أتمتة

POST https://api.mail.land/v1/marketing/automations/{id}/activate

ينقل الأتمتة من حالة Draft أو Paused إلى Active. بمجرد التفعيل، تبدأ الأتمتة بتسجيل المشتركين عند إطلاق المحفز.

لا يُتحقق من التفعيل نفسه مقابل توثيق النطاق. خطوة SendEmail التي يُصل إليها بلا أي نطاق موثّق بالكامل تُحجز، ولا تُتخطى: تُعاد مراجعتها على فترات متزايدة (١٥ دقيقة، ثم حتى كل ٦ ساعات) وتُرسَل بمجرد توثيق نطاق. وإذا لم يُوثَّق أي نطاق خلال ٧ أيام من أول استحقاق الخطوة، يُوسَم التسجيل بـ Failed (يُحتسب ضمن totalFailed) بدلاً من بقائه محجوزاً إلى الأبد: فينجح التفعيل دون أي نطاق موثّق، لكن لا يُسلَّم شيء حتى تُوثّق نطاقاً، وتنتهي التسجيلات التي لا تزال منتظرة بعد أسبوع بدلاً من أن تظل محجوزة إلى ما لا نهاية.

Activate an automation
curl -X POST https://api.mail.land/v1/marketing/automations/4f8k2m9p1q6z3s/activate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

إيقاف أتمتة مؤقتاً

POST https://api.mail.land/v1/marketing/automations/{id}/pause

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

Pause an automation
curl -X POST https://api.mail.land/v1/marketing/automations/4f8k2m9p1q6z3s/pause \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

أرشفة أتمتة

POST https://api.mail.land/v1/marketing/automations/{id}/archive

يؤرشف الأتمتة، وهو أمر يمكن القيام به من أي حالة بما في ذلك Active. تُخفى الأتمتة المؤرشفة من عروض القوائم الافتراضية.

تُوقف الأرشفة كلاً من التسجيلات الجديدة والخطوات اللاحقة للمشتركين المسجَّلين بالفعل: يبقى كل تسجيل عند خطوته الحالية، تماماً مثل الإيقاف المؤقت. وبخلاف الإيقاف المؤقت، لا توجد نقطة نهاية تُعيد تفعيل أتمتة Archived، لذا لا يُحلّ هذا التوقف من تلقاء نفسه.

Archive an automation
curl -X POST https://api.mail.land/v1/marketing/automations/4f8k2m9p1q6z3s/archive \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

تكرار أتمتة

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

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

Duplicate an automation
curl -X POST "https://api.mail.land/v1/marketing/automations/4f8k2m9p1q6z3s/duplicate?name=Copy%20of%20Welcome%20Series" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

التفعيل اليدوي

POST https://api.mail.land/v1/marketing/automations/{id}/trigger
طلب التفعيل اليدوي
{
  "subscriberIds": ["3m8k1p9x4q7n2z", "6q2n9k4x1p8m3z", "1x7m3q8k2n9p4z"]
}

تسجيل مشتركين محددين يدوياً في الأتمتة. يجب أن تكون الأتمتة بحالة Active ونوع المحفز Manual (5).

Trigger automation manually
curl -X POST https://api.mail.land/v1/marketing/automations/4f8k2m9p1q6z3s/trigger \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"subscriberIds": ["3m8k1p9x4q7n2z", "6q2n9k4x1p8m3z", "1x7m3q8k2n9p4z"]}'

تتبع التسجيل

يتم تتبع تقدم كل مشترك خلال الأتمتة كتسجيل:

الحالةالقيمةالوصف
Active0يتحرك حالياً عبر الخطوات
Paused1التسجيل متوقف مؤقتاً
Completed2أنهى جميع الخطوات
Failed3خطوة SendEmail لا تملك قالباً في هذا المستأجر: مفقود منذ البداية أو محذوف لاحقاً. يُحتسب ضمن totalFailed الخاص بالأتمتة
Unsubscribed4ألغى المشترك اشتراكه أثناء التسلسل

لا توجد حالة تسجيل Cancelled. تتضمن استجابة تفاصيل الأتمتة أعداداً إجمالية للتسجيلات بصيغة totalEnrolled وtotalCompleted (وليس totalEnrollments/activeEnrollments/completedEnrollments/failedEnrollments).

حذف أتمتة

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

يحذف الأتمتة وخطواتها وبيانات التسجيل نهائياً.

يُسمح بالتحديث والحذف لـ أي حالة باستثناء Active، وليس فقط Draft/Paused (للتحديث) أو Draft/Archived (للحذف) كما ذكرت نسخ سابقة من هذه الصفحة.

Delete an automation
curl -X DELETE https://api.mail.land/v1/marketing/automations/4f8k2m9p1q6z3s \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

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

الحالةالرمزالوصف
400VALIDATION_FAILEDحقول مطلوبة مفقودة أو تكوين خطوات غير صالح: بما في ذلك خطوة SendEmail بلا templateId أو خطوة Condition بإعدادات (settings) غير قابلة للتقييم
400TEMPLATE_NOT_FOUNDلا يشير templateId الخاص بخطوة SendEmail إلى قالب في مستأجرك
400INVALID_REQUESTاسم الأتمتة موجود مسبقاً أو انتقال حالة غير صالح
403FORBIDDENصلاحيات غير كافية
404RESOURCE_NOT_FOUNDالأتمتة غير موجودة، أو انتقال الحالة غير صالح (تحديث/تفعيل/إيقاف بحالة خاطئة، حذف أتمتة Active)

نقاط نهاية الأتمتة لا تعيد أبدًا الاستجابة 422.

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

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

في هذه الصفحة