مشترکین

مدیریت مخاطبین مشترک، وارد کردن لیست‌ها و پیگیری تعامل

مخاطبین مشترک ایمیل خود را مدیریت کنید. هر مشترک دارای پروفایلی با ردیابی تعامل، فیلدهای سفارشی و مدیریت وضعیت است.

وضعیت‌های مشترک

وضعیت	مقدار	توضیح
`Active`	0	مشترک شده و در حال دریافت ایمیل
`Unsubscribed`	1	از دریافت ایمیل انصراف داده
`Bounced`	2	bounce سخت ثبت شده
`Complained`	3	شکایت اسپم ثبت کرده
`Pending`	4	رزرو‌شده: MailLand هیچ فرآیند double opt-in ندارد، بنابراین چیزی هرگز این وضعیت را تنظیم نمی‌کند

optInMethod و فیلدهای consent* روی یک مشترک فقط به‌عنوان شاهد ثبت می‌شوند، و هیچ گردش‌کار تأییدی را هدایت نمی‌کنند.

ایجاد مشترک

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

Create subscriber request

{
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1234567890",
  "company": "Acme Corp",
  "mailingListId": "ddv6ou6kz4wbto",
  "source": "api",
  "birthday": "1990-05-14",
  "customFields": {
    "plan": "enterprise",
    "region": "us-west"
  }
}

فیلد	نوع	الزامی	توضیح
`email`	string	بله	آدرس ایمیل
`firstName`	string	خیر	نام
`lastName`	string	خیر	نام خانوادگی
`phone`	string	خیر	شماره تلفن
`company`	string	خیر	نام شرکت
`mailingListId`	string	خیر	لیست پستی برای افزودن
`source`	string	خیر	منبع اشتراک (مثلاً `api`، `form`، `import`)
`birthday`	string	خیر	`YYYY-MM-DD`. توسط محرک اتوماسیون `DateBased` خوانده می‌شود
`customFields`	object	خیر	فیلدهای سفارشی کلید-مقدار

Create a subscriber

curl -X POST https://api.mail.land/v1/marketing/subscribers \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "mailingListId": "ddv6ou6kz4wbto",
    "source": "api"
  }'

پاسخ

Subscriber response

{
  "id": "exz31qoqlf01sj",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1234567890",
  "company": "Acme Corp",
  "status": "active",
  "statusName": "Active",
  "source": "api",
  "mailingListId": "ddv6ou6kz4wbto",
  "mailingListName": "Product Updates",
  "customFields": {
    "plan": "enterprise",
    "region": "us-west"
  },
  "subscribedAt": "2026-02-17T12:00:00Z",
  "unsubscribedAt": null,
  "createdAt": "2026-02-17T12:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

فهرست مشترکین

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

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

List subscribers

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

دریافت جزئیات مشترک

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

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

Get subscriber details

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

Subscriber detail response

{
  "id": "exz31qoqlf01sj",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1234567890",
  "company": "Acme Corp",
  "status": "active",
  "source": "api",
  "mailingListId": "ddv6ou6kz4wbto",
  "mailingListName": "Product Updates",
  "customFields": { "plan": "enterprise" },
  "birthday": "1990-05-14",
  "emailsSent": 50,
  "emailsOpened": 25,
  "emailsClicked": 10,
  "lastEmailSentAt": "2026-02-17T09:30:00Z",
  "lastEmailOpenedAt": "2026-02-16T15:20:00Z",
  "lastEmailClickedAt": "2026-02-15T11:10:00Z",
  "openRate": 50.0,
  "clickRate": 40.0,
  "subscribedAt": "2026-01-15T08:00:00Z",
  "createdAt": "2026-01-15T08:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

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

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

Update subscriber request

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phone": "+1234567890",
  "company": "TechCorp",
  "mailingListId": "ddv6ou6kz4wbto",
  "customFields": { "plan": "pro" },
  "birthday": "1990-05-14",
  "status": "Active"
}

PUT کل پروفایل را جایگزین می‌کند، نه ادغام می‌کند. firstName، lastName، phone، company و mailingListId همگی هنگام حذف با null (یا حذف از لیست) بازنویسی می‌شوند، نه اینکه بدون تغییر بمانند. حذف mailingListId عضویت مشترک در لیست را حذف می‌کند. هر فیلدی را که می‌خواهید نگه دارید ارسال کنید، از جمله mailingListId. فقط customFields و status هنگام حذف بدون تغییر باقی می‌مانند. birthday قاعده‌ی خودش را دارد: حذف‌کردن فیلد آن را بدون تغییر می‌گذارد، ارسال "birthday": null آن را پاک می‌کند، و مقدار YYYY-MM-DD آن را تنظیم می‌کند، رشته‌ی خالی ("") با 400 رد می‌شود. اگر گیرنده از قبل مخاطبی بدون لیست دارد، عضویتی که حذف می‌کنید فقط به‌عنوان تاریخچه نگه داشته می‌شود: دیگر در مخاطبان نمایش داده نمی‌شود و لغو اشتراک‌ها، سوابق رضایت و تاریخچه کمپین‌های آن حفظ می‌شود.

Update a subscriber

curl -X PUT https://api.mail.land/v1/marketing/subscribers/exz31qoqlf01sj \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "company": "TechCorp",
    "mailingListId": "ddv6ou6kz4wbto",
    "customFields": { "plan": "pro" },
    "status": "Active"
  }'

لغو اشتراک مشترک

POST https://api.mail.land/v1/marketing/subscribers/{id}/unsubscribe

یک لغو اشتراک محدود به لیست مشترک را ثبت می‌کند (یا در صورتی که مشترک لیستی نداشته باشد، محدود به همه‌ی ارسال‌های بازاریابی) و وضعیت مشترک را به Unsubscribed همراه با زمان unsubscribedAt تغییر می‌دهد. ایمیل‌های تراکنشی تحت تأثیر این فراخوانی قرار نمی‌گیرند.

Unsubscribe a subscriber

curl -X POST https://api.mail.land/v1/marketing/subscribers/exz31qoqlf01sj/unsubscribe \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

حذف مشترک

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

مشترک و داده‌های تعامل او را به‌طور دائمی حذف می‌کند. لغو اشتراک‌ها و سرکوب‌ها حفظ می‌شوند، بنابراین افزودن دوباره‌ی همان آدرس آن را دوباره مشترک نمی‌کند.

Delete a subscriber

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

وارد کردن مشترکین

POST https://api.mail.land/v1/marketing/subscribers/import

وارد کردن مشترکین از محتوای CSV:

Import request

{
  "mailingListId": "ddv6ou6kz4wbto",
  "csvContent": "email,firstName,lastName\n[email protected],John,Doe\n[email protected],Jane,Smith",
  "source": "csv_import",
  "updateExisting": true
}

فیلد	نوع	الزامی	توضیح
`mailingListId`	string	خیر	لیست پستی هدف
`csvContent`	string	بله	داده‌های CSV: به هشدار قالب زیر مراجعه کنید؛ سطر سرستون به‌عنوان سرستون استفاده نمی‌شود

سطر اول به‌عنوان سرستون در نظر گرفته می‌شود و نادیده گرفته می‌شود، صرف‌نظر از محتوای آن: هرگز برای نگاشت ستون‌های ۱ تا ۳ به فیلدها خوانده نمی‌شود. ستون‌ها موقعیتی هستند: ستون ۱ همیشه email است، ستون ۲ همیشه firstName، ستون ۳ همیشه lastName؛ هر ستون دیگری نادیده گرفته می‌شود، به‌جز ستونی با سرستون birthday (بدون حساسیت به حروف بزرگ/کوچک، در هر موقعیتی پس از ستون ۱)، که بر اساس نام سرستونش خوانده می‌شود نه موقعیتش. مقدار آن باید YYYY-MM-DD باشد؛ مقدار نامعتبر برای هر سطر در errors گزارش می‌شود و آن مخاطب همچنان ایمپورت می‌شود، فقط بدون تاریخ تولد. فایلی بدون سرستون birthday دقیقاً مانند قبل رفتار می‌کند. مقادیر بر اساس کاما‌های ساده تقسیم می‌شوند، بنابراین مقداری که شامل کاما درون کوتیشن باشد پشتیبانی نمی‌شود و به‌اشتباه تقسیم خواهد شد. پاسخ همچنین شمارنده‌های importedNewMembershipForExistingRecipient، updatedMembership، alreadyMember، suppressed و skippedDuplicateInFile را علاوه بر آنچه در زیر نشان داده شده اضافه می‌کند.

Import subscribers

curl -X POST https://api.mail.land/v1/marketing/subscribers/import \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "mailingListId": "ddv6ou6kz4wbto",
    "csvContent": "email,firstName,lastName\[email protected],John,Doe\[email protected],Jane,Smith",
    "source": "csv_import",
    "updateExisting": true
  }'

Import response

{
  "imported": 50,
  "updated": 10,
  "skipped": 5,
  "errors": [
    "Invalid email: not-an-email",
    "Could not resolve a recipient identity for: [email protected]"
  ]
}

مشترکینی که وارد (import) می‌شوند، اتوماسیون SubscriberJoins را فعال می‌کنند: برای هر عضویتی که این عملیات واقعاً ثبت می‌کند، درست مانند یک ایجاد تکی از طریق POST /v1/marketing/subscribers. مخاطبی که از قبل روی لیست هدف است، تکرار درون همان فایل، یا سطری که به‌دلیل تعارض (TenantId, Email) از دست می‌رود، ثبت‌نام نمی‌شود. اگر لیست هدف یک اتوماسیون SubscriberJoins فعال داشته باشد (یا مستأجر یکی داشته باشد که به لیستی محدود نیست)، وارد کردن فایلی از مخاطبین جدید اکنون آن اتوماسیون را برای تک‌تک آن‌ها ارسال می‌کند: اندازه‌ی import را متناسب با این موضوع در نظر بگیرید. سرکوب (suppression) همچنان اعمال می‌شود: ثبت‌نام هرگز از کنار یک مخاطب سرکوب‌شده عبور نمی‌کند.

صادر کردن مشترکین

GET https://api.mail.land/v1/marketing/subscribers/export

پارامتر	نوع	توضیح
`mailingListId`	string	فیلتر بر اساس لیست پستی
`status`	int	فیلتر بر اساس وضعیت

یک فایل CSV با نام subscribers_yyyyMMdd_HHmmss.csv برمی‌گرداند.

Export subscribers

curl "https://api.mail.land/v1/marketing/subscribers/export?mailingListId=ddv6ou6kz4wbto" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -o subscribers_export.csv

آمار مشترکین

GET https://api.mail.land/v1/marketing/subscribers/stats

پارامتر	نوع	توضیح
`mailingListId`	string	فیلتر بر اساس لیست پستی

Get subscriber stats

curl "https://api.mail.land/v1/marketing/subscribers/stats?mailingListId=ddv6ou6kz4wbto" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Subscriber stats response

{
  "total": 1500,
  "active": 1200,
  "unsubscribed": 200,
  "bounced": 80,
  "complained": 10,
  "pending": 10
}

تعداد مشترکین

GET https://api.mail.land/v1/marketing/subscribers/count

پارامتر	نوع	توضیح
`mailingListId`	string	فیلتر بر اساس لیست پستی

Get subscriber count

curl "https://api.mail.land/v1/marketing/subscribers/count?mailingListId=ddv6ou6kz4wbto" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Count response

{
  "count": 1500,
  "mailingListId": "ddv6ou6kz4wbto"
}

رشد مشترکین

GET https://api.mail.land/v1/marketing/subscribers/growth

پارامتر	نوع	پیش‌فرض	توضیح
`days`	int	30	دوره بازگشتی (حداکثر ۹۰)
`mailingListId`	string	-	فیلتر بر اساس لیست پستی

Get subscriber growth

curl "https://api.mail.land/v1/marketing/subscribers/growth?days=30&mailingListId=ddv6ou6kz4wbto" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Growth response

{
  "dataPoints": [
    {
      "date": "2026-02-17",
      "newSubscribers": 50,
      "unsubscribes": 5,
      "cumulativeTotal": 1500
    }
  ],
  "totalNew": 500,
  "totalUnsubscribes": 50,
  "netGrowth": 450,
  "currentTotal": 1500
}

پاسخ‌های خطا

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

مراحل بعدی

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

مشترکین

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

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

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

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

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

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

لغو اشتراک مشترککپی پیوند بخش

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

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

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

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

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

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

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

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

در این صفحه