MailLandDocs
بازاریابی

سگمنت‌ها

ایجاد سگمنت‌های پویا بر اساس ویژگی‌ها و رفتار مشترکین

سگمنت‌ها گروه‌های پویای مشترکین هستند که بر اساس شرایط تعریف می‌شوند. برخلاف لیست‌های ثابت، سگمنت‌ها به‌طور خودکار با تغییر داده‌های مشترکین به‌روزرسانی می‌شوند. از سگمنت‌ها برای هدف‌گذاری کمپین‌ها به مخاطبان خاص بر اساس ویژگی‌ها، تعامل و رفتار استفاده کنید.

انواع تطابق

نوع تطابقمقدارتوضیح
All0همه شرایط باید تطابق داشته باشند (منطق AND)
Any1هر شرطی می‌تواند تطابق داشته باشد (منطق OR)

ایجاد سگمنت

POST https://api.mail.land/v1/marketing/segments
Create segment request
{
  "name": "Active Engaged Users",
  "description": "Users who opened or clicked in last 30 days",
  "matchType": "All",
  "conditions": [
    {
      "field": "lastemailopenedat",
      "operator": "inlast",
      "value": "30"
    },
    {
      "field": "status",
      "operator": "equals",
      "value": "Active"
    }
  ]
}
فیلدنوعالزامیتوضیح
namestringبلهنام سگمنت (منحصر به فرد در هر فضای کاری)
descriptionstringخیرتوضیحات سگمنت
matchTypestringخیرAll (پیش‌فرض) یا Any
conditionsarrayبلهحداقل یک شرط
Create a segment
curl -X POST https://api.mail.land/v1/marketing/segments \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Active Engaged Users",
    "matchType": "All",
    "conditions": [
      { "field": "lastemailopenedat", "operator": "inlast", "value": "30" },
      { "field": "status", "operator": "equals", "value": "Active" }
    ]
  }'

پاسخ

Segment response
{
  "id": "0qe306asbapwvd",
  "name": "Active Engaged Users",
  "description": "Users who opened or clicked in last 30 days",
  "matchType": "all",
  "matchTypeName": "All",
  "conditionsCount": 2,
  "subscriberCount": 450,
  "createdAt": "2026-02-17T12:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

پاسخ‌ها matchType را به‌صورت حروف کوچک برمی‌گردانند ("all" / "any") حتی اگر درخواست ایجاد/به‌روزرسانی "All"/"Any" را بپذیرد.

فیلدهای شرط مبتنی بر باز شدن/کلیک (emailsopened، lastemailopenedat و غیره) شامل فعالیت ماشینی هستند، پیش‌بارگذاری Apple Mail Privacy Protection و اسکنرهای امنیتی لینک، که امروز فیلتر نمی‌شوند.

یک endpoint مستندنشده‌ی GET /{id}/preview نیز وجود دارد که نمونه‌ای از مشترکینی را که در حال حاضر با شرایط بخش مطابقت دارند برمی‌گرداند.

فیلدهای شرط

فیلدهای رشته‌ای

فیلدها: email، firstname، lastname، company، source، phone

عملگرتوضیحنیاز به مقدار
equalsتطابق دقیقبله
notequalsنامساویبله
containsشامل زیررشتهبله
notcontainsشامل نیستبله
startswithشروع بابله
endswithپایان بابله
isemptyفیلد خالی استخیر
isnotemptyفیلد خالی نیستخیر

فیلدهای عددی

فیلدها: emailssent، emailsopened، emailsclicked

عملگرتوضیحنیاز به مقدارنیاز به مقدار ۲
equalsمساویبلهخیر
notequalsنامساویبلهخیر
greaterthanبزرگتر ازبلهخیر
greaterthanorequalبزرگتر یا مساویبلهخیر
lessthanکوچکتر ازبلهخیر
lessthanorequalکوچکتر یا مساویبلهخیر
betweenبین دو مقداربلهبله

فیلدهای تاریخ

فیلدها: createdat، subscribedat، lastemailsentat، lastemailopenedat، lastemailclickedat

عملگرتوضیحنیاز به مقدار
equalsدر تاریخ مشخصبله (تاریخ ISO)
beforeقبل از تاریخبله (تاریخ ISO)
afterبعد از تاریخبله (تاریخ ISO)
onorbeforeدر یا قبل ازبله (تاریخ ISO)
onorafterدر یا بعد ازبله (تاریخ ISO)
betweenبین دو تاریخبله (value + value2)
inlastدر N روز گذشتهبله (عدد صحیح روز)
isnullتاریخ تنظیم نشدهخیر
isnotnullتاریخ تنظیم شدهخیر

فیلدهای شمارشی

فیلد: status

عملگرتوضیحمقادیر
equalsمساوی با وضعیتActive، Unsubscribed، Bounced، Complained
notequalsنامساوی باهمان مقادیر

نمونه شرط‌ها

Email domain filter
{ "field": "email", "operator": "contains", "value": "example.com" }
High engagement filter
{ "field": "emailssent", "operator": "between", "value": "10", "value2": "50" }
Recent clickers
{ "field": "lastemailclickedat", "operator": "inlast", "value": "7" }
Missing first name
{ "field": "firstname", "operator": "isempty" }

دریافت متادیتای سگمنت

دریافت تمام فیلدها، عملگرها و مقادیر شمارشی موجود برای ساخت شرایط سگمنت:

GET https://api.mail.land/v1/marketing/segments/metadata/fields
Get segment metadata
curl https://api.mail.land/v1/marketing/segments/metadata/fields \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Metadata response
{
  "fields": [
    {
      "name": "email",
      "label": "Email",
      "type": "string",
      "operators": ["equals", "notequals", "contains", "notcontains", "startswith", "endswith", "isempty", "isnotempty"],
      "enumValues": null
    },
    {
      "name": "status",
      "label": "Status",
      "type": "enum",
      "operators": ["equals", "notequals"],
      "enumValues": ["Active", "Unsubscribed", "Bounced", "Complained"]
    }
  ]
}

فهرست سگمنت‌ها

GET https://api.mail.land/v1/marketing/segments
پارامترنوعپیش‌فرضتوضیح
cursorstring-نشانگر مبهم از nextCursor صفحهٔ قبل. برای صفحهٔ اول حذف کنید.
limitint20تعداد در هر صفحه
searchstring-جستجو بر اساس نام یا توضیحات
sortBystring-فیلد مرتب‌سازی
sortDescboolfalseمرتب‌سازی نزولی
List segments
curl "https://api.mail.land/v1/marketing/segments?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

دریافت جزئیات سگمنت

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

سگمنت کامل همراه با شرایط را برمی‌گرداند:

Get segment details
curl https://api.mail.land/v1/marketing/segments/0qe306asbapwvd \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Segment detail response
{
  "id": "0qe306asbapwvd",
  "name": "Active Engaged Users",
  "description": "Users who engaged in last 30 days",
  "matchType": "all",
  "matchTypeName": "All",
  "conditionsCount": 2,
  "subscriberCount": 450,
  "conditions": [
    {
      "field": "lastemailopenedat",
      "operator": "inlast",
      "value": "30",
      "value2": null
    },
    {
      "field": "status",
      "operator": "equals",
      "value": "Active",
      "value2": null
    }
  ],
  "cachedCount": 450,
  "cachedAt": "2026-02-17T10:00:00Z",
  "createdAt": "2026-01-10T08:00:00Z",
  "updatedAt": "2026-02-17T10:00:00Z"
}

پیش‌نمایش شرایط

پیش‌نمایش نتیجه‌ی شرایط پیش از ایجاد سگمنت. ارزیابی سگمنت همیشه به مشترکینی با وضعیت Active محدود می‌شود، بنابراین شرطی مانند status notequals Active هیچ‌کس را مطابقت نمی‌دهد.

POST https://api.mail.land/v1/marketing/segments/preview
Preview request
{
  "conditions": [
    { "field": "lastemailopenedat", "operator": "inlast", "value": "30" }
  ],
  "matchType": "All"
}
Preview segment conditions
curl -X POST https://api.mail.land/v1/marketing/segments/preview \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      { "field": "lastemailopenedat", "operator": "inlast", "value": "30" }
    ],
    "matchType": "All"
  }'
Preview response
{
  "count": 450,
  "sampleEmails": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
}

دریافت تعداد سگمنت

GET https://api.mail.land/v1/marketing/segments/{id}/count
Get segment count
curl https://api.mail.land/v1/marketing/segments/0qe306asbapwvd/count \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Count response
{
  "segmentId": "0qe306asbapwvd",
  "count": 450
}

به‌روزرسانی کش سگمنت

اجبار به شمارش مجدد مشترکین منطبق:

POST https://api.mail.land/v1/marketing/segments/{id}/refresh
Refresh segment cache
curl -X POST https://api.mail.land/v1/marketing/segments/0qe306asbapwvd/refresh \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Refresh response
{
  "segmentId": "0qe306asbapwvd",
  "count": 460,
  "refreshedAt": "2026-02-17T12:30:00Z"
}

کپی از سگمنت

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

یک سگمنت جدید با شرایط کپی‌شده ایجاد می‌کند. پارامتر name اختیاری است.

Duplicate a segment
curl -X POST "https://api.mail.land/v1/marketing/segments/0qe306asbapwvd/duplicate?name=Copy%20of%20Segment" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

به‌روزرسانی سگمنت

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

بدنه درخواست با درخواست ایجاد مطابقت دارد. به‌روزرسانی سگمنت به‌طور خودکار تعداد کش‌شده آن را به‌روز می‌کند.

Update a segment
curl -X PUT https://api.mail.land/v1/marketing/segments/0qe306asbapwvd \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Active Engaged Users (Updated)",
    "matchType": "All",
    "conditions": [
      { "field": "lastemailopenedat", "operator": "inlast", "value": "14" },
      { "field": "status", "operator": "equals", "value": "Active" }
    ]
  }'

حذف سگمنت

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

حذف یک سگمنت، آن را از هر کمپینی با وضعیت Draft یا Scheduled که آن را هدف قرار داده جدا می‌کند (فیلد segmentId کمپین پاک می‌شود)، در نتیجه آن کمپین بدون مخاطب می‌ماند: ارسال آن یا 422 برمی‌گرداند یا به هیچ‌کس تحویل داده نمی‌شود. کمپینی که از قبل در وضعیت Sending است تحت تأثیر قرار نمی‌گیرد، زیرا مخاطبانش پیش‌تر مشخص شده‌اند.

Delete a segment
curl -X DELETE https://api.mail.land/v1/marketing/segments/0qe306asbapwvd \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

پاسخ‌های خطا

وضعیتکدتوضیح
400VALIDATION_FAILEDنام یا شرایط نامعتبر
400INVALID_REQUESTنام سگمنت از قبل وجود دارد
403FORBIDDENدسترسی ناکافی
404RESOURCE_NOT_FOUNDسگمنت یافت نشد

مراحل بعدی

  • کمپین‌ها: هدف‌گذاری کمپین‌ها با سگمنت‌ها
  • اتوماسیون‌ها: اتوماسیون‌ها در حال حاضر بر اساس عضویت در سگمنت فعال نمی‌شوند
  • مشترکین: مدیریت مخاطبان در سگمنت‌های خود

لیست‌ها

سازماندهی مشترکین در لیست‌های پستی برای کمپین‌های هدفمند

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

تنظیم دنباله‌های ایمیل مبتنی بر رویداد که به‌طور خودکار بر اساس رفتار مشترکین اجرا می‌شوند

در این صفحه

انواع تطابقایجاد سگمنتپاسخفیلدهای شرطفیلدهای رشته‌ایفیلدهای عددیفیلدهای تاریخفیلدهای شمارشینمونه شرط‌هادریافت متادیتای سگمنتفهرست سگمنت‌هادریافت جزئیات سگمنتپیش‌نمایش شرایطدریافت تعداد سگمنتبه‌روزرسانی کش سگمنتکپی از سگمنتبه‌روزرسانی سگمنتحذف سگمنتپاسخ‌های خطامراحل بعدی