اتوماسیون‌ها

اتوماسیون‌ها به شما امکان می‌دهند دنباله‌های ایمیل چند مرحله‌ای ایجاد کنید که توسط رویدادهای مشترک فعال می‌شوند. یک محرک تعریف کنید، دنباله‌ای از مراحل بسازید و MailLand هر بار که محرک فعال می‌شود، جریان را به‌طور خودکار اجرا می‌کند.

محرک‌های اتوماسیونکپی پیوند بخش

هر اتوماسیون با یک محرک واحد آغاز می‌شود:

| Manual | 5 | فعال‌سازی دستی از طریق API |

وضعیت‌های اتوماسیونکپی پیوند بخش

انواع مراحلکپی پیوند بخش

هر اتوماسیون شامل یک دنباله مرتب از مراحل است:

شخصی‌سازی (Personalization)کپی پیوند بخش

مراحل ایمیل اتوماسیون از تگ‌های ادغام {{variable}} پشتیبانی می‌کنند که به ازای هر گیرنده از رکورد خودِ مشترک ثبت‌نام‌شده جایگزین می‌شوند.

<p>Hi {{firstName}}, here's what's new this month.</p>

املای قدیمی‌تر 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"
    }
  ]
}

فیلد segmentId روی یک اتوماسیون وجود ندارد: این فیلد اینجا وجود ندارد (سگمنت‌ها جای دیگری استفاده می‌شوند، مثلاً در کمپین‌ها). محتوای مرحله‌ی SendEmail از templateId می‌آید، نه از htmlContent/textContent/fromName/fromEmail درون‌خطی.

فیلدهای مراحلکپی پیوند بخش

مرحله SendEmail (type: 0):

هیچ htmlContent/textContent/fromName/fromEmail/replyTo درون‌خطی روی یک مرحله وجود ندارد. فرستنده به‌صورت ثابت noreply@<اولین دامنه‌ی کاملاً تأییدشده> است که همراه با نام فضای کاری نمایش داده می‌شود: به ازای هر مرحله قابل تنظیم نیست.

مرحله Wait (type: 1):

مرحله Condition (type: 2):

یک مرحله‌ی Condition یک دروازه است، نه یک انشعاب: فهرست خطی مراحل مسیر دومی ندارد. وقتی ارزیابی درست باشد، ثبت‌نام به مرحله‌ی بعدی ادامه می‌یابد. وقتی ارزیابی نادرست باشد، ثبت‌نام همان‌جا (Completed) پایان می‌یابد و هیچ مرحله‌ی بعدی برای آن مشترک اجرا نمی‌شود.

مقایسه‌ها مقایسه‌ی رشته‌ای بدون حساسیت به بزرگی/کوچکی حروف هستند، همان عملگرهایی که سگمنت‌ها هم‌اکنون ارائه می‌دهند. 400 VALIDATION_FAILED هنگام ایجاد/به‌روزرسانی زمانی بازگردانده می‌شود که conditionField ناشناخته باشد، conditionOperator یکی از مقادیر بالا نباشد، یا conditionValue برای عملگری که به آن نیاز دارد وجود نداشته باشد.

مراحل AddToList / RemoveFromList (type: 3, 4):

مرحله UpdateSubscriber (type: 5):

مرحله Webhook (type: 6):

درخواست‌های گام Webhook با کلید گیرندهٔ همان گام امضا می‌شوند (X-MLND-Signature که مثل وب‌هوک مشتری بررسی می‌شود): هر نشانی URL جداگانهٔ گام کلید خودش را دارد، پس هیچ گیرنده‌ای نمی‌تواند به‌جای گیرندهٔ دیگر امضا کند. کلیدها را با GET /v1/marketing/automations/{id}/webhook-signing-secrets بخوانید و با POST /v1/marketing/automations/{id}/webhook-signing-secrets/regenerate عوض کنید، نسخه‌بندی را ببینید. برای عوض‌کردن کلید فقط یک گیرنده، { "webhookUrl": "…" } را بفرستید.

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

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

دریافت جزئیات اتوماسیونکپی پیوند بخش

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

اتوماسیون کامل شامل تمام مراحل را برمی‌گرداند:

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). بدنه درخواست مشابه درخواست ایجاد است.

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 منتقل می‌کند. پس از فعال‌سازی، اتوماسیون شروع به ثبت‌نام مشترکین هنگام فعال‌شدن محرک می‌کند.

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

اتوماسیون را متوقف می‌کند. هیچ مشترک جدیدی ثبت‌نام نمی‌شود، و مشترکینی که در حال حاضر در دنباله هستند دیگر پیش نمی‌روند: هر ثبت‌نام در مرحله‌ی فعلی خود متوقف می‌شود. فعال‌سازی دوباره‌ی اتوماسیون هر ثبت‌نام متوقف‌شده را از همان‌جایی که بود ادامه می‌دهد و هر چه در طول توقف سررسید شده باشد را تحویل می‌دهد.

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 قابل انجام است. اتوماسیون‌های بایگانی‌شده از نماهای پیش‌فرض فهرست پنهان هستند.

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 اختیاری است.

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) باشد.

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"]}'

ردیابی ثبت‌نامکپی پیوند بخش

پیشرفت هر مشترک در اتوماسیون به عنوان یک ثبت‌نام ردیابی می‌شود:

هیچ وضعیت ثبت‌نام Cancelledای وجود ندارد. پاسخ جزئیات اتوماسیون شامل شمارش تجمیعی ثبت‌نام‌ها به‌صورت totalEnrolled و totalCompleted است (نه totalEnrollments/activeEnrollments/completedEnrollments/failedEnrollments).

حذف اتوماسیونکپی پیوند بخش

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

اتوماسیون، مراحل و داده‌های ثبت‌نام آن را به‌طور دائمی حذف می‌کند.

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

پاسخ‌های خطاکپی پیوند بخش

اندپوینت‌های اتوماسیون هرگز پاسخ 422 برنمی‌گردانند.

مراحل بعدیکپی پیوند بخش

• کمپین‌ها: ارسال کمپین‌های یک‌بار مصرف
• مشترکین: مدیریت مخاطبینی که اتوماسیون‌ها هدف قرار می‌دهند
• لیست‌ها: سازماندهی مشترکین در لیست‌ها برای محرک‌ها