لیست‌ها

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

لیست‌های پستی به شما امکان می‌دهند مشترکین را برای کمپین‌های هدفمند در گروه‌ها سازماندهی کنید. هر رکورد مشترک به یک لیست تعلق دارد، اما یک آدرس ایمیل یکسان می‌تواند رکوردهای جداگانه‌ای در چند لیست داشته باشد، و کمپین‌ها می‌توانند یک لیست خاص یا بخشی درون آن را هدف قرار دهند.

ایجاد یک لیست

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

Create list request

{
  "name": "Product Updates",
  "description": "Subscribers interested in product announcements"
}

فیلد	نوع	الزامی	توضیحات
`name`	string	بله	نام لیست (باید در هر فضای کاری منحصر به فرد باشد)
`description`	string	خیر	توضیحات لیست

Create a mailing list

curl -X POST https://api.mail.land/v1/marketing/lists \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Product Updates", "description": "Product announcements" }'

پاسخ

List response

{
  "id": "vtmlew96u277jq",
  "name": "Product Updates",
  "description": "Product announcements",
  "isActive": true,
  "subscriberCount": 0,
  "createdAt": "2026-02-17T12:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

فهرست تمام لیست‌های پستی

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

پارامتر	نوع	پیش‌فرض	توضیحات
`cursor`	string	-	نشانگر مبهم از `nextCursor` صفحهٔ قبل. برای صفحهٔ اول حذف کنید.
`limit`	int	20	تعداد آیتم در هر صفحه
`search`	string	-	جستجو بر اساس نام
`isActive`	bool	-	فیلتر بر اساس وضعیت فعال
`sortBy`	string	-	فیلد مرتب‌سازی
`sortDesc`	bool	false	مرتب‌سازی نزولی

List all mailing lists

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

List response

{
  "items": [
    {
      "id": "vtmlew96u277jq",
      "name": "Product Updates",
      "description": "Product announcements",
      "isActive": true,
      "subscriberCount": 2500,
      "createdAt": "2026-01-10T08:00:00Z",
      "updatedAt": "2026-02-17T12:00:00Z"
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

دریافت جزئیات لیست

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

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

Get list details

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

List detail response

{
  "id": "vtmlew96u277jq",
  "name": "Product Updates",
  "description": "Product announcements",
  "isActive": true,
  "subscriberCount": 2500,
  "activeSubscribers": 2300,
  "unsubscribedCount": 150,
  "bouncedCount": 50,
  "createdAt": "2026-01-10T08:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

به‌روزرسانی یک لیست

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

Update list request

{
  "name": "Product Announcements",
  "description": "Updated description",
  "isActive": true
}

فیلد	نوع	الزامی	توضیحات
`name`	string	بله	نام لیست (باید منحصر به فرد باشد)
`description`	string	خیر	توضیحات لیست
`isActive`	bool	خیر	وضعیت فعال (پیش‌فرض: `true`)

isActive فقط یک برچسب است: تنظیم آن روی false مانع ارسال نمی‌شود. هیچ‌چیز در کد کمپین یا worker این فیلد را برای جلوگیری از هدف قرار گرفتن این لیست توسط یک کمپین نمی‌خواند.

Update a mailing list

curl -X PUT https://api.mail.land/v1/marketing/lists/vtmlew96u277jq \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Announcements",
    "description": "Updated description",
    "isActive": true
  }'

حذف یک لیست

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

لیست پستی را حذف می‌کند. مشترکین این لیست حذف نمی‌شوند اما mailingListId آن‌ها پاک می‌شود (یک کلید خارجی SetNull). لغو اشتراک‌های محدود به لیست هنگام حذف یک لیست حفظ می‌شوند.

اگر یکی از مشترکین این لیست از قبل یک مخاطب بدون لیست داشته باشد (مثلاً چون عضو لیست دیگری بوده که پیش‌تر حذف شده است)، همان مخاطب باقی می‌ماند و عضویت او در این لیست فقط به‌عنوان سابقه نگه داشته می‌شود: دیگر در فهرست مخاطبان نمایش داده نمی‌شود و هیچ کمپین یا اتوماسیونی آن را هدف قرار نمی‌دهد. لغو اشتراک‌ها، سوابق رضایت و سابقهٔ کمپین‌های آن حفظ می‌شوند.

Delete a mailing list

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

پاسخ‌های خطا

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

مراحل بعدی

مشترکین: مشترکین را به لیست‌های خود اضافه کنید
بخش‌بندی‌ها: بخش‌های پویا در داخل لیست‌ها ایجاد کنید
کمپین‌ها: کمپین‌ها را به لیست‌های خود ارسال کنید

لیست‌ها

ایجاد یک لیستکپی پیوند بخش

پاسخکپی پیوند بخش

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

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

به‌روزرسانی یک لیستکپی پیوند بخش

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

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

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

در این صفحه